Make intentions clear
Time to read
, 546 words, 5th grade
One of the most difficult truths to get across to new coders is that coding is not about telling the machine what do do. That part is easy.
Rather, all code is a conversation with the next coder to come along.
Programming is the art of telling another human being what one wants the computer to do.
As such, your code needs to be clear and unambiguous.
Why then do so many coders value “clever” or terse code over clear and unambiguous code? It is as if they were getting a buck for every character they saved.
This is not to promote verbosity for its own sake. Verbose or flowery code adds cognitive load to no purpose. What we want to achieve here is to reduce cognitive load, not bloat it up. Ergo, murder your darlings.
Whenever you feel an impulse to perpetrate a piece of exceptionally fine writing, obey it — whole-heartedly — and delete it before sending your manuscript to press. Murder your darlings
The truth is that you should be able to read the code itself as if reading a novel. An easy one. Foundation, rather than Gravityʼs Rainbow or Ulysses. Dr. Seuss, if at all possible. Green Eggs and Ham, anyone?
Too often, coders focus on terse code and then think, “Iʼll explain it in the comments.”
But comments are almost worse than overly-terse code. They inflate the verbosity of the code. This makes the code harder to read. (This is also a problem with documenting code in the comments.)
Worse, it is easy for them to get out of sync with the code. The next coder comes along and changes the code, but forgets to update the comment. Ow.
Every time you write a comment, you should grimace and feel the failure of your ability of expression.
We repeat: any decent coder should find reading your code as easy as reading a good book. A young adult book, not War and Peace. A comment should only be necessary when you had to use a workaround. Then, it is mandatory.
A comment explaining the workaround and why it was necessary prevents you from coming back a month later and saying to yourself, “What the hell was I thinking?”
Then rewriting the code, and then saying, sadly, “Oh! Thatʼs what I was thinking!”
Doh!
Name well. Do not fear long names. Do not use abbreviations unless they are universal. Name functions with verbs to show that they are actions. Name variables with nouns to show that they are static.
And consider this: if you cannot make your intentions clear, then likely they are not clear to you either. Vague and ambiguous code suggests vague and ambiguous thinking.
You do not really understand something unless you can explain it to your grandmother.
Take the time to do it right the first time by making your code as clear and comprehensible as possible. You — or the next coder — will save far more time down the road. Take the long view. Short-term approaches are expensive.
Making intentions clear is also an essential part of universal design. Coders can be dis-abled by our thoughtlessness as well.