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.
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:
Note: Doc-blocks and comments are having full sentences starting with a capital letter and ending with a period.
Using a formatter like
clang-formatmake style debates disappear.
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.
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.
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.
File: .clang-tidy
Checks: '-*,modernize-*'
WarningsAsErrors: 'modernize-*'
HeaderFilterRegex: '.*'
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.