-
Notifications
You must be signed in to change notification settings - Fork 82
Formatting
Formatting code is a job for computers. When humans try to make an objective decision about something so subjective, we spiral into unproductive discussions during code reviews.
ABC is all about scalability, so we want a formatting setup that works when our repository gets large. The Angular project takes about 90s to re-format everything, which is too long for such a common developer task.
If we upgrade the formatter or change the formatting options, we don't want to re-format the whole repository, as that would cause nasty rebasing of pending Pull Requests and pollute the source control history. At the same time, we want the CI to be able to check that developers actually ran the formatter.
To accomplish these things, we need the formatter to work together with the version control system, so that only modified regions need to be re-formatted. For this reason, we recommend using clang-format like in this example repo, rather than Prettier. (Also, clang-format has more features, such as alphabetically sorting imports)
Follow the instructions at https://github.com/angular/clang-format#checking-formatting to set up automated formatting for modified code regions.
Bazel has its own formatter, called Buildifier. Since there are fewer BUILD files in a typical project, we currently don't have a way to incrementally re-format only the changed code - we always re-format everything.
To run Buildifier, first add install the com_github_bazelbuild_buildtools repository into your WORKSPACE file, like the example. To run it, we recommend adding a script to your package.json similar to the example. Since we don't want to assume developers will have a Buildifier binary already on their machine (and also they might have a different version), we compile Buildifier and then run it. After it's compiled the first time, Bazel will cache the binary so we only eat the cost the first time.
On the CI, we enforce formatting by running buildifier -mode=check - see the lint job in the example. Note that we run this before we install the node_modules, so that we don't need to worry about it triggering on BUILD files that come from installed dependencies. (Also, it's nice that the CI gives quicker feedback without having to install any npm packages. Currently the example has the buildifier command included in the docker image - this is a recipe for version skew issues. We are working to get the same Bazel caching on CircleCI so a re-build is free, and we can use the same command as in the package.json file in the example.