At Intersec, we aim at maintaining a consistent style throughout all the code, depending on the programming language. For example, the C codebase is the most consistent, with our coding rules being enforced on code review. This enforcement, however, can lead to significant time loss and frustrations when patches must be repushed to be adapted to specific rules.
In the past, there has been several attempts at configuring auto-formatting tools. They were never fully satisfactory because several of our coding rules did not fit into the limited configuration options of these tools. This subject was born out of these attempts. However, instead of focusing on adapting the tools to our coding rules, we considered doing the opposite. What about adapting our coding rules (in particular, some of those peculiar rules) so that auto-formatting tools could be applied easily? After all, if some of our rules are too specific to exist in popular tools, maybe those rules cause more harm than improvement to our code.
First step was Python, which we use extensively: for testing, in our build system as well as specific APIs. Python is the language where a specific coding style is the least enforced. Our guidelines tell us to follow PEP8, but this has never been particularly applied, hence a very heterogeneous codebase.
We looked into autopep8, yapf and black. Given the state of our codebase, any of these tools would involve significant changes when applied on all files. We decided to go with the most opinionated one, after discussing specific configuration options.
As expected, the changes were significant. A quick
indicated that we had about 200k lines of python code. Launching
black on every python file resulted in about +56k additions and
-34k deletions. These are huge changes: although we are happy about the
formatting, these changes practically ensure conflicts during branches merges,
which may generate significant time loss as well.
Funnily enough, runing
black on our whole codebase generated
two errors where the output of
black was not idempotent,
in old code with dubious style.
black was smart enough
to detect that and provide the diff, so that the formatting could be fixed by
We considered using
eslint instead, as we already use
(happily) as a linter. Adding a few indentation rules, we can use
eslint --fix as a sort of auto formatter. It is less opinionated
prettier, but fits nicely with our codebase.
For 236k lines of code, running
eslint --fix on all JS files
resulted in about 5k modifications only that fall into two main categories:
- Specific coding rules that did not match with eslint rules.
- Badly indented code that was fixed.
This is pretty good. The changes are relatively minimal, and this could be used to make sure that the code is properly formatted on new commits. However, it may require some user reformatting, as some constructs may cause some very ugly indentation (for example, declaring an object on multiple lines in a function call aligns the object fields with the opening bracket of the object, which can lead to very high indentation).
We also have around 120k lines of typescript. We are currently in the
process of migrating our
tslint configuration to
eslint, which, when finished, will also allow us to format our
typescript code using
Our C Codebase was the most problematic. It uses Blocks, has grown to use a lot of idiosyncratic syntaxes and allows using higher-level data types through many custom macros. When used to it, the coding rules make the code easily readable for us. For a formatting tool however, not so much. C is notoriously hard to parse, and formatting tools can have a hard time understanding which identifiers are types, or which macros are used to simulate keywords or blocks.
The goal was to use
clang-format, which supports blocks
natively. However, the development version was needed to get support for some
latest features, including whitelisting of specific macros as keywords
The result is not entirely convincing though. We triggered a few bugs which breaks the indentation, and some of the reformatting leaves the code arguably less readable than before. This could possibly be alleviated by modifying our coding rules significantly to improve the formatting, but that would involve a lot of modifications to the whole codebase, which we would rather avoid.