Skip to content

Add and enforce new ".clang-format" based on Microsoft base style

Eduardo Almeida requested to merge edalm/ns-3-dev:coding-style-revamp into master

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 #includes (detected after sorting the includes according to LLVM best practices) [https://llvm.org/docs/CodingStandards.html#include-style].
  • Update dead #includes 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 into utils/check-style.py.
  • Update utils/check-style.py with multithread support.
  • Delete old utils/utils.h file with documentation for uncrustify.
  • Rename check-style.py to check_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

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:

Edited by Eduardo Almeida

Merge request reports