Skip to content

Coding Standards & Conventions

Why are Standards & Conventions Necessary?

Coding standards and conventions are essential in software development for several reasons.

They ensure consistency and readability in the codebase, making it easier for developers to understand and collaborate on projects. They promote best practices and maintainability, reducing the likelihood of bugs and making code easier to debug and maintain in the long run. Lastly, adherence to coding standards improves code quality and enhances software reliability, scalability, and performance. Overall, coding standards and conventions are necessary to foster efficient and effective development processes and produce high-quality, maintainable software.

Consistent conventions make it easier to navigate and debug code, reduce errors, improve code quality, facilitate efficient code reviews, and last but not least, allow for smooth Git merges.
Overall, coding conventions enhance code clarity and foster a unified coding style across projects and teams.

Agree and Enforce

Tools can be used, such as code linters, formatters, and analyzers to automate and enforce the standards. Coding standards should be agreed upon by the team and documented in a shared repository.

Next to format styling it also must include:

  • Comment placement: Comments in definitions should be placed above the code they describe since it is easier to merge branches.
  • Doc-block: Doc-blocks for at least all functions and public or protected class methods and data members.

Note: Doc-blocks and comments are having full sentences starting with a capital letter and ending with a period.

Enforcing in Code/Projects as a Gatekeeper

Using a formatter like clang-format make style debates disappear.

Git Commit Hook (local)

Enforcement can be achieved by running a check script on all committed files from .git/hooks before a commit.

Virtual Example:

#!/bin/env bash

# Run Clang-Tidy on staged files
staged_files=$(git diff --cached --name-only --diff-filter=ACMR "*.cpp" "*.h")
if [ -n "$staged_files" ]; then
    echo "Running Clang-Tidy on staged files..."
    clang-tidy -p build/ $staged_files
    CLANG_TIDY_RESULT=$?
    if [ $CLANG_TIDY_RESULT -ne 0 ]; then
        echo "Clang-Tidy check failed. Please fix the reported issues before committing."
        exit 1
    fi
fi

# Continue with the commit
exit 0

Real World Example:

The shell script check-format.sh is part of a library which supports building C++ projects in general and is a submodule of a C++ projects Git repository.
The file has to be symlinked into the root directory of the project where the Git commit hook is created to it. The script eventually calls clang-format.sh with option --branch <branch-name> passing the branch it is merged with. This makes the script only check the changed files compared to that branch.

Using GitLab Pipelines (remote)

Configure GitLab's first stage or step in a CI/CD pipeline to fail when the styling format check fails.

Virtual Example:

stages:
  - check
  - build

clang-tidy:
  stage: check
  image: clang:latest
  script:
    - apt-get update && apt-get install -y clang-tidy
    - clang-tidy -p build/ source/**/*.cpp
  only:
    - branches

build:
  stage: build
  script:
    - mkdir build && cd build
    - cmake ..
    - make
  only:
    - branches

Real World Example:

In the CI/CD pipeline of a C++ project, the stage check-env is configured to run the script check-format.sh and fails when the formatting is incorrect.

Coding in C++

Using Clang Tidy & Format

Clang-Tidy is specifically used because it is tightly integrated with the Clang compiler, providing accurate code analysis for C and C++. It supports modern C++ features, offers extensive customization options, and has a wide range of checks tailored to Clang's parsing and compilation process. Clang-Tidy's integration with popular tools and its extensive set of built-in checks make it a popular choice for bug detection, coding style enforcement, and code quality improvements in C and C++ projects.

Clang Tidy Configuration

File: .clang-tidy

Checks: '-*,modernize-*'
WarningsAsErrors: 'modernize-*'
HeaderFilterRegex: '.*'

Clang Formatting Configuration

The .clang-format file is used to configure the Clang-Format tool. It is a YAML file with a number of options that can be used to customize the formatting of C++ code.

This .clang-format version enforces a styling which uses Allman style braces, tabs for indents and more to allow for easier merging of code. Tabs distance can be adjusted by an individual developer to suit their personal preferences.