Coding styles
Coding style 101
-
Have a coding style and follow it. Consistency is really important for code readability. And this goes for whatever code you’re working on - code that can seem throwaway at first may end up being re-used in a production project.
Not sure where to start? Have a look at some coding styles that have been created for you. PEP8 is a good start for Python. Google’s C++ style is pretty agreeable.
-
Use a linter to help maintain the code style. Even if it’s just run locally. It makes conforming to good practices easy, and can prevent bugs. When you are writing code, you shouldn’t be too worried about the fine points of the style, e.g. whitespace. Computers are much better than humans at catching this stuff. But remember to commit your code locally first, then run the linter and check the diff. Sometimes linters do bad things.
-
Use common sense. There’s no coding style that works perfectly for all people all the time. When there’s some ambiguity about what the style dictates, use common sense to pick the most readable approach. If the linter wants to do something that makes the code harder to read, then consider disabling the relevant rule/option. Computers are much worse than humans at knowing what’s readable to a human.
Some random collected thoughts on coding styles
-
I’m often surprised when I see coding styles that seem to treat vertical whitespace like it’s a limited resource. A line-break here or there can really help to separate code into related blocks. Just like a gap between paragraphs in English text.
-
I also find it frustrating where coding styles have arbitrary numbers in them. I mean, we’re programmers - we should treat all magic numbers with suspicion right? A good example is a rule about maximum line length. About every year or two, the screens I use for development get bigger the resolution higher. And yet you still have people using some low and arbitrary max line length, like 100 characters or something. I’m not advocating crazy-long lines, but I am advocating common sense on behalf of the coder. IMHO a line has to get pretty long before it becomes less readable (by scrolling right a little), than when it is awkwardly broken into multiple lines.
-
Consistency is key. It’s hard to come up with a heuristic for readability because your idea of clarity is likely to be different to the next person’s. I once worked with a developer who advocated three-space tabs. Crazy I know, but I’m sure if you’ve been using that for a few years, everything else looks bad.
-
My personal guidelines to measure readability:
-
Consistent is better than inconsistent
-
Symmetric is better than asymmetric
-
Spacious is better than cramped
-
Concise is better than verbose, which is better than sparse
-
-
As an English speaker, I often think about the way that the English language is written – the phrases, sentences, paragraphs and how those are phrased, formed and separated – and how this can be applied to a programming language to make reading the code more natural. While the compiler contrains you from making your code anything close to a natural language, you can use underscores, spaces, tabs and vertical whitespace to form “sentences” and “paragraphs”.
