The 3 Levels of Code Consistency
Post from October 16, 2017 (↻ April 28, 2022), filed under Web Development.
This article first appeared at CSS-Tricks.
When working on an article about user-centered web development I ended up exploring a bit more the topic of consistency in code. Consistency is a factor for code quality and one of the key reasons why we need coding guidelines. Interestingly enough, I found, there are three levels of consistency: individual, collective, and institutional.
Level 1: Individual Consistency
At a basic level, when there’s little standardization in our organization (or when we simply work alone), consistency just means to be consistent with ourselves. We benefit from always formatting code the same way.
If we, just the one of us each, usually omit unneeded quotes around attribute values (absolutely valid, as such projects prove), we should always do so. If we prefer not to end the last declaration in a CSS rule with a semicolon, we should not do so. If we prefer to always use tabs, we should always do so.
Level 2: Collective Consistency
At the next level, and here we assume there to be code from other developers or third parties, consistency means to follow the code style used wherever we touch code. We should respect and stay consistent with the code style prevalent in the files we touch.
When we help our colleague launch a site and tweak their CSS, we format the code the way they did. When we tweak some core files of our content management systems (if that was so advisable), we do what they do. When we write a new plugin for something, we do it the way other plugins are written.
Level 3: Institutional Consistency
Finally, normally a level reached in bigger organizations, consistency means adhering to (or first creating) the organization’s coding guidelines and style guides. If the guidelines are well-established and well-enforced, this type of consistency offers the most power to also effect changes in behavior—individual consistency offers almost no incentive for that, collective consistency only temporarily.
When we normally indent with spaces and the corp style guide says tabs, we use tabs. When our colleagues launch their mini-project and, when helping out, we discover their code not to be compliant with the corporate guidelines, we take the time to refactor it. When we start something new, perhaps based on some different language, we kick off a guideline setup and standardization process.
❧ These three consistency levels are not mutually exclusive.
In our own affairs, we should at least strive for level 1, but personally I’ve made great experience hooking myself up to some external level 3 standard (I’m following Google’s HTML/CSS guidelines with the only exception of using tabs instead of spaces) and defining, in detail, some complementary level 1-style standard (as with a predefined selector order).
Whenever we deal with other developers, but only if there’s lack of a wider standard, we should at least aim for level 2 consistency, that is, respect their code. We touch something in their domain, we write it like they would do.
When we are in a bigger organization—though “bigger” can truly start at two people—this same idea of level 2 consistency prevails, but we can now think of setting up standards to operate at level 3. There, we can even marry the two levels: Follow the coding guidelines, but when we touch something that violates the guidelines and we don’t have the time to re-format it, we follow the style dominant in that code.
From my experience, being aware of these levels alone helps a great deal writing more consistent, and with that quite better code.
I’m Jens Oliver Meiert, and I’m an engineering manager and author. I’ve worked as a technical lead for Google, I’m close to the W3C and the WHATWG, and I write and review books for O’Reilly. Other than that, I love trying things, sometimes including philosophy, art, and adventure. Here on meiert.com I share some of my views and experiences.
If you have questions or suggestions about what I write, please leave a comment (if available) or a message.
Have a look at the most popular posts, possibly including:
Looking for a way to comment? Comments have been disabled, unfortunately.
Perhaps my most comprehensive book: The Web Development Glossary (2020). With explanations and definitions for literally thousands of terms from Web Development and related fields, building on Wikipedia as well as the MDN Web Docs. Available at Apple Books, Kobo, Google Play Books, and Leanpub.