Add and enforce new ".clang-format" based on Microsoft base style
This MR contains the proposal for the coding style revamp and enforcement using clang-format
based on the Microsoft
base style. Please use this MR to discuss specific issues regarding the ns-3 coding style. For a more generic coding style discussion, please refer to the parent issue #677.
NOTE: The clang-tidy
work was split into MR !1082 (merged).
MR Status
-
Finish .clang-format
[waiting for feedback]. -
Review and convert the NS_CHECK_STYLE_{ON,OFF}
macro to// clang-format {on,off}
. -
Convert tabs to spaces in files excluded from clang-formatting. -
Fix missing #include
s (detected after sorting the includes according to LLVM best practices) [https://llvm.org/docs/CodingStandards.html#include-style]. -
Update dead #include
s that are causing differences between clang-format-14 and clang-format-15. -
Update utils/check-style.py
to use the new tools. -
Merge utils/trim-trailing-whitespace.py
intoutils/check-style.py
. -
Update utils/check-style.py
with multithread support. -
Delete old utils/utils.h
file with documentation foruncrustify
. -
Rename check-style.py
tocheck_coding_style.py
. This change is meant to alert users that this script is completely new and has new options. Also, use underscore according to Python PEP8. -
Add job to the GitLab CI/CD to check the coding style. -
Define a list of supported versions of clang-format. -
Update documentation. -
Discuss migration to Microsoft base style [https://mailman.isi.edu/pipermail/ns-developers/2022-September/015766.html]. -
Fix formatting of some files before general clang-format application -
Add check to check-style-clang-format.py
to detect tabs in the middle of lines and replace them with spaces. -
Remove emacs line from all files [separate MR].
Clang-format Preview
A preview of the clang-format applied to the current codebase can be found here
- GNU style: edalm/ns-3-dev@c2773c0b
- Microsoft style [updated]: edalm/ns-3-dev@504e7f0c
Coding Style Discussion
A summary of the coding style discussion on specific rules for clang-format can be found on this Excel shared file.
List of Supported Versions
The list of clang-format versions that are currently supported include:
- clang-format-14
Clang-format Usage
To test this MR, please install clang-format-14
using your OS's package manager.
IDE Integration
Clang-format automatically integrates with modern IDEs (e.g., VS Code) that read the .clang-format
file and automatically formats the code on save or on typing. Please refer to the documentation of your IDE for more information.
Manual Usage in the Terminal
Clang-format can be manually run on the terminal by applying the following commands in the ns-3 root directory:
clang-format -i $FILE
To check that a file is properly formatted, run the following command on the terminal. If the code is well formatted, the process will exit with code 0; if is not, it will exit with code of 1 and indicate the lines that should be formatted.
clang-format --dry-run --Werror $FILE
Disable Formatting in Specific Files or Lines
To disable formatting in specific lines, please surround the lines that should not be formatted with the following "special comments" [example from official documentation]:
int formatted_code;
// clang-format off
void unformatted_code ;
// clang-format on
void formatted_code_again;
To exclude the whole file from being formatted, please add the special comments in the top and bottom of the file.
Update Pending Merge Requests and Out-of-Tree Code
Clang-format comes with two companion tools to help reformat Git patches:
-
git clang-format ...
documentation -
clang-format-diff ...
documentation