Unlike many, I do actually believe that code aesthetics matter. On the other hand, I’ll also admit to being as much of an arrogant elitist about code as I am about music. This is why I like CoffeeScript and Anton Webern. 2 spaces vs 4 spaces? Spaces vs Tabs? Indent case statements within a switch? I’ve got an opinion. The fact remains that it’s much more important that everyone uses the same conventions than exactly what that convention is. So I keep my stylistic tics to myself and listen to Polly Harvey on headphones where the noise doesn’t frighten my wife.
One funny thing is that people don’t seem to extend this logic out of their team or project. There’s usually a dominant answer to these stylistic questions for whatever programming language you’re using. Don’t like it? Write your own programming language while listening to Laurie Anderson (or whatever you’re into).
For the most part, just doing what everyone else does answers most aesthetic coding standards questions that may arise. It reduces stupid fatiguing stylistic discontinuities and lets you get on with actually reading the code.
Standards Creep
So, do you need a coding standards document? Well, that’s really going to depend on how many violations you’re seeing. Bear in mind that beginners aren’t going to perceive the patterns as easily as the competent. However, here’s where the spectre of best practices rears its head again. Once you start to document what people’s code looks like, it’s very tempting to move into what their code actually does. Again, you end up creating a document that, at best, annoys your best programmers. At worst, it creates a culture in which your best programmers are regarded as loose cannons and mediocrity is regarded as the highest goal.
So here’s my own contribution to “best practice” coding for readability: don’t be a jerk. At the risk of being prescriptive and contradicting everything I’ve already said:
- Don’t write bad confusing code and then a long comment explaining it. Write better code.
- It’s OK to have one character identifiers with tight scope. Especially if you’re going to use it repeatedly.
- When have wide scope, write words out in full rather than using a contraction, unless it’s a very well understood one. Searching for stuff is hard when you have to guess.
- And needless to say, spell things correctly. If you’re not sure, type the word into Google. I do.
- If jargon doesn’t make things more concise, don’t use it. That said, use commonly accepted terminology.
- Don’t reuse identifiers to mean different things at different times.
- Don’t be vague. isActive and shouldBeActive are different concepts. It’s amazing how many people just call the identifier “active” is both circumstances.*
- Identify things by what you’re doing with them, not what they are.
Unless, of course, following these rules to the letter would make you act like a jerk.
*To get to nitty-gritty style point, the standard in C# is that you would identity “is active” with “active”. Still, don’t ever identity “should be active” with “active”. Equally, if you’re in lisp, “should be active” shouldn’t be named “active?”.
Colour Coding 