Software design principles for teams: The Principle of Appropriate Automation.
Automated style checking is your friend. Maximise this within reason.
Background
This is an elaboration of one of the principles I originally published in the following article…
Principle
Automated style checking is your friend. Maximise this within reason.
I debated whether this principle was substantial enough to include on this list. Ultimately, I erred on the side of inclusivity as the clause “within reason” is doing a lot of heavy lifting in the wording above. Style checkers are abundant, often free and generally easy to use, however too many teams use them as the only hammer in their software design toolbox, with expected results.
At the heart of the nuance around the current generations of automated style checkers is the admission that they are crude instruments and will ultimately only gnaw at the low hanging fruit of software design decisions. They are maturing in sophistication though: I have a colleague who is a big fan of the Sonarcube’s Cognitive Complexity metric because of the more holistic approach it takes (https://www.sonarsource.com/docs/CognitiveComplexity.pdf), and this maturation will no doubt continue apace.
Automated style checking works best when:
You have churn in your team, and new team members have not yet internalized the stylistic norms. Conversely, an established team should have normed towards such a common coding style that the irregular warning or error from the style checker should illicit reactions of “I’d forgotten we even used this, it has been so long since it raised anything!”.
There are no barriers to running this tooling locally to give developers fast feedback before integrating code centrally1. Checkers targeting the enterprise (looking at you again, Sonarcube) seem to take “run locally as part of developers workflow” as a nice-to-have requirement, which is unsurprisingly given who is signing the purchase order, but frustrating for a team whether tools add a lot of friction (in terms of complexity or commercial barriers) to getting fast feedback.
When retrospectively applying checkers to existing codebases, you have an easy way to ratchet up the tolerance of the checkers over time. It is less than motivating to know you have 3000 style errors in your build pipeline, but if can adjust thresholds to incrementally raise the stylistic bar, you turn the check feedback from noise to useful. This is not something that many tools support natively, so you often need to manually tweak the thresholds.
Ultimately, the current state of style checkers should allow you to reduce the time your team spends talking about relatively trivial style issues, freeing up this time for more serious design discussions which cannot be automatically adjudicated. Use style checkers so teams can effectively focus on significant design choices, not as an under-powered one-ring-to-bind-them-all design traffic cop. The following Twitter thread contains some examples of style checker horror stories, but almost everyone I know has experience with the downside of applying this sort of tooling in a heavy handed manner.
My bias is showing here. Ideally, my teams work primarily using Trunk Based Development (TBD) with automated builds only on trunk. If you are working primarily on branches with CI builds on each branch, then this requirement is likely less important to you.