Static analysis tools examine code solely using text. We use the linters and formatters to maintain code quality, style, and error prevention. 

make check can be used to ensure that your PR will pass Github actions in regards to the linting and formatting tools.

Linting

What and Why

Linters run diagnostic checks on source code that make code cleaner, less error-prone, and readable. They might warn that an unused variable is present, change a variable name to be consistent with other variables, warn about coding style such as using braces correctly. This is a great tool to avoid bugs, adhere to best practices, and learn the correct way to use larger libraries. Our goal for using such a tool is to make code more consistent, have less bugs, and use libraries correctly.

Details

We use Clang-Tidy-17 to lint our C code. Clang-Tidy is part of the LLVM project. The installation of the tool is handled through the install script.

The tool is run on all C code files through the Makefile using make tidy. This will apply formatting changes. make tidy-check will show any errors and warnings as Makefile errors. This is used for enforcing the tool in Github actions.

The rules for linting are detailed in the configuration file called .clang-tidy in the root directory of the repository. It was generated using clang-tidy --dump-config and modified as appropriate. When clang-tidy is run, it looks for this file in the current working directory.

Most ruled provided by clang-tidy are focused on C++ source files. We look at all the groups of rules and decided on the specific set in the .clang-tidy file, along with some changes to the rule's values.

A big part of clang-tidy's usefulness is to enforce naming conventions for code. We decided to use Google's naming style detailed here.

Formatting

What and Why

Formatters take the workload off the programmer to write code that is consistent in formatting. Coding format includes use of spaces, tabs, alignment, and line length. It uses principles to automatically edit code to create a consistent and clean code format. This is important to make code easier to read, understand, and catch errors. When multiple contributors work on a project, multiple formats are implemented. Formatters help align and enforce a singular, good format. Our goal for using such a tool is to make code easier to read, understand and consistent.

Details

We use Clang-Format-17 to format our C code. Clang-Format is part of the LLVM project. The installation of the tool is handled through the install script.

The tool is run on all C code files through the Makefile using make format. This will apply formatting changes. make format-check will show any formatting errors as Makefile errors. This is used for enforcing the tool in Github actions.

The format followed is based on Google's formatting style. Differences include:

• Indentations were changed from 2 to 4 

The configuration file that details specifics for Clang-Format are in .clang-format in the root directory of the repository. It was generated using clang-format -style=google -dump-config > .clang-format and aforementioned changes were made. When clang-format is run, it looks for this file in the current working directory.

Usage (TL;DR)

1. Make sure you have the latest version of clang-format and clang-tidy. These can be installed from the install script.
2. Run make check to see if your code passes the linting/formatting checks. It will tell you what step it fails on.
3. If it fails the formatting step (which is clang-format), run make format to apply formatting changes. This will move things around to make your code prettier. Go back to step 1 and run make check again.
4. If it fails the linting step (which is clang-tidy), read the error(s) it's spitting out and try to fix them. These may be more varied since linting is static analysis for bugs, naming checks, and more. Go back to step 1 and run make check again.
5. Once make check passes, run make leader (or equivalent to build code for the desired target) and ensure that there are no compilation errors. Since make format and make tidy change your code pretty heavily, there is a good chance that they make your code fail compilation. Fix the errors and do steps 1-5 again.