There are many in the development community who recognize and espouse the wisdom of having a common style guide for writing code. The benefits include things such as consistency, ease of developer onboarding, and more. Perhaps even more important is that it helps to avoid so-called religious debates… for example, should we use “tabs” or “spaces”? Single quotes or double quotes? And so on. The more these decisions can be decided ahead of time, the less time the team will spend on these decisions.
Examples of Coding Style Guides
In the industry, many companies and projects publish their coding styles. See below for an example:
Here at Clear Function, we’ve found that style guides such as these are great starting places when beginning a new project.
Automating Code Style
That said, there is still the effort in reviewing code to ensure that code matches up to the dictated style. How much time should you really spend looking over a pull request looking for invalid coding styles? Even more so, how “pushy” should you be?
Ideally, these decisions should be handled automatically by your build process. There are many examples of so-called “linting” tools. The original term “lint” was coined in 1978 at Bell Labs, and it has mostly stuck. Below is a brief list of some of the great linting tools that you can use are:
As an example of what a failing lint test looks like, see below:
********* Running rubocop ********* time bundle exec rubocop Inspecting 286 files ...................................................................................................................................................................................................................................................................................C.......... Offenses: app/controllers/api/v1/donors_controller.rb:152:5: C: Use a guard clause instead of wrapping the code inside a conditional expression. unless @donor ^^^^^^ 286 files inspected, 1 offense detected Command exited with non-zero status 1 13.27user 0.58system 0:14.02elapsed 98%CPU (0avgtext+0avgdata 79220maxresident)k 5384inputs+0outputs (0major+51121minor)pagefaults 0swaps make: *** [rubocop] Error 1
This is an example of our
rubocop check failing our build. This is caught before anyone even begins looking at a pull request. In addition, it means that no bike-shedding happens because everyone knows how the build is configured.
Even more so, many of these linting tools can hook into your editing environment so that you’ll find formatting issues well before the code ever reaches your build server.
Automating Formatting
What if we take this one step further? Linting is great, but what if our editors prevent us from writing code that doesn’t line up with our style guide in the first place? After all, it is a pain to deal with this on almost every pull request…
One of the best implementations of this is gofmt. Gofmt is a automatic formatter made by the Go team for the Go language. Instead of individual teams or companies choosing their own preference for formatting Go, the language designers themselves have dictated the format.
Since the release of gofmt, many other languages and communities have begun to release similar tools that help with this. One in particular is prettier. Prettier was originally created for JavaScript-flavored languages (e.g. ES2017, JSX and Flow). Today it supports a wide variety of languages with even more in progress.
Here’s what an editor with Prettier integrated looks like when a document is saved:
Outside of the prettier ecosystem, Elixir even ships with its own automatic formatter. It is likely that many other languages and communities will begin to adopt either Prettier or their own formatting as the automatic formatting of code is especially beneficial.