Yesterday, I wrote about how self-documenting code (without any comments or a README) is an anti-pattern for a code base.
Today, I want to talk about another one: ignoring code base style norms.
A well-maintained code base should look like one person wrote it, even when it’s been maintained by a team of people.
This isn’t purely an aesthetic preference. Inconsistent norms around things like how you author functions, how you define variables, and how your structure code can lead to every developer just “doing their own thing.” Over the life of a project, this is how you end up with spaghetti code.
There’s no “right way” or “correct” set of norms around code base style, but I personally like to see a consistent set of practices around…
- Function declarations vs. function expressions vs. arrow functions
- When to use
- Tabs vs. spaces (it should always be tabs 🙈)
- Semicolons (or not) and brackets (or not)
- Trailing commas after the last item in an array or object
As an example, when I see most of a code base written using
const for libraries and
let for everything else, but one file contains a bunch of
var declarations, I know that other file was written by someone else.
I also know they didn’t adhere to the code base norms, which makes me a bit nervous about what else they’ve touched in the code base.
If you’re creating a README for your project (and you should!), a code styleguide is a good thing to add to it.