Documentation? Shmockumentation!

When I spout my views on documentation, I know all too well that they not universally popular. Also, I’m aware that they are quite rare. I can’t remember anybody high-fiving me and shouting “Yessss! You nailed it Phil, that’s exactly how I see it” - and I have a good memory.

A lot of folk think I’m saying it just to be provocative, but I sincerely believe that code should contain as few comments as possible and preferably none. By all means some description needs to be somewhere – a separate document preferably but a stone tablet will do for me as long it’s not in the code. Hear me out before you spit your coffee while snorting in derision at me. Here are my golden rules of Shmockumentation

Firstly, what runs? Code, not documentation. What just failed? Code, not documentation. What is it precisely you need to fix right now? Same answer, hence Rule 1 is: Code is code and comments are comments and never the twain shall meet. If you want to know what code is supposed to be doing, then feel free to read the documentation as long as you accept rule 2. If on the other hand you want to know what the code is actually doing, there is only one place to find that: in the code itself.

Rule 2 is derived from the truth that both me and the Arduino ESP core god-coders are not the only programmers that don’t like doing documentation: no-one does. We’re coders, we code therefore we are. Documentation is for wimps. This inexorably gives rise to the reality that documentation is always, but always out of date because it’s always going to get fixed once the code is finally working. 

And at the moment it’s not. That’s not only understandable, it’s actually predictable because what are we trying to produce, to deliver? Code, not documentation. Anybody who shouts “code and documentation” is not going to last long on the team when the hammer is down. Imagine, if you will, this conversation with the project manager, especially if the project manager is me:

Coder: “I don’t think my code is going to ready on time…”

PM: “Why not?”

Coder: “Well I’m very keen on good documentation, so…”

PM (interrupting): “We all are, of course - we’re professionals!” while thinking internally “When exactly did I lose my soul and find this management-speak garbage so easy to slipstream into the conversation because everybody above coder expects to hear it?”[1]

Coder: “yes, of course, but I have let the code slip a little as I’ve spent more time than I should have on documentation”

PM (with furrowed brow): “How is that possible? How can you accurately document what isn’t actually finished yet? What if you find a late design flaw that needs a strategy change? You’d have to rewrite a huge chunk of the documentation, which means that all the time you have wasted - sorry, “spent”, no, wasted on the gold-plated but now utterly useless documentation could have been spent writing the code which is what we pay you for and it might have already been finished!”

<long pause…much fierce eye avoidance>

Coder: “Sorry I hadn’t looked at it that way before now…”

PM: (never one to miss an opportunity): “Exactly!” and then, remembering the HR B.S. – sorry, “guidelines” – “Look, put it to one side and concentrate on the code from now on, eh? If it’s ready by Monday, I’ll buy you a couple of beers, OK?”

Coder(thinking “Hey, maybe not all PMs are meanies!”): “Thanks, I’ll get right back on it!”

PM (absentmindedly reverting to type): “And if it’s not, you can pick up your cards on the way out!”

Fanciful?  Or more real than we care to admit? Code is what matters and even (rare) good documentation just gets in the way of the code when you are looking for a subtle bug. Worse it can lead to confirmation bias:

// calculate commission percentage

comm=…

can easily seduce the bug-hunter by leading her to think: “simple percentage calculation one-liner, no-one gets those wrong at this level, can’t be that, next!”...and she has just missed the late-night-tired-and-wanna-go-home “schoolkid error” division by zero.

Had the comment not been there, she’d have more likely thought “What’s ‘comm’ and what’s it doing here? Hang on a minute, that divisor hasn’t been given a value, yet! Bingo! ZERODIV error! That was an easy one, now back to my own code!”

Which leads us to rules 2a and 3. 2a is that not only is documentation always out-of-date, it is so the moment it is written. It just is. Why? - Because people like me are too busy coding to update it, that’s why.

Rule 3 is a killer. It’s that you can’t tell a piece if documentation is good or bad until you analyse the code that it relates to. It's only "good" if it accurately describes the code that follows. Thus in order to make that assessment, you have to read all of the documentation, read all of the code then mentally analyse and compare both.

Can you see where I’m going with this yet? If it is good documentation then you have learnt nothing: because you were always going to analyse the code anyway so you will know what it actually does! All you did is waste that time reading comments when you could have been bug-hunting. So the code works and the docs describe it...but what matters is: the code works (Rule 1) - more importantly - it works irrespective of the presence of the comments.

If, on the other hand it’s bad documentation, you now have to make time to take it out . In doing so you nicely proved my point in that if it weren’t there at all, you’d have finished the whole thing earlier. Of course , there is NO WAY you'd leave in known bad comments, is there? To do so just proves rule 2a: "...people like me are too busy coding to update it..."

In summary: bad comments slow you down and confuse you, good comments just slow you down. Either way: any comments slow you down. Lose them.

The final nail in the coffin for comments in code is rule 4 - clarity.

If you think your code needs documenting, is it because it is not clear - even to you, its author? If it's clear by- definition - it doesn't need comments. If it is not clear, you are a bad programmer, and no amount of commentary will fix that!

If your code works as per spec, then the spec is the required documentation and all else is superfluous. If the code doesn’t do what the spec says, you are in for a chat with the PM and some advice on how not to end up in the dole queue. If it does what the spec says but needs additional explanation then it may well work but it’s not good code, because it’s not clear and the PM is free to see you now.

There’s no way out. Documentation in production code is a BAD THING.

Code runs, documentation doesn’t. Good code is self-documenting. Only in our AI dreams is good documentation self-coding. Did I say “dreams”? I meant “nightmares” – we’d all be out of a job and the Wimps would rule the world. Bin the docs, fix the code. I like the ring of that, I may have it carved on my gravestone.

In closing I have a tale from the archives to illustrate these point in a self-deprecatory manner:

In my very early days as a programmer (think "vacuum tubes") I discovered a neat but very tricky way to shave a few bytes off an already well-bloated and much-amended tattered lace curtain of a program (good lord, I have just realised I can even remember its name: “VA54”. Snappy, eh?).

Very pleased with myself and somewhat smugly, I wrote a natty comment (mainly just to amuse me) which read “Clever Coding Conserves Core!”[2] and forgot to take it out before getting my paper tape punched up (yes, it was THAT long ago!) A couple of weeks later I had another amendment to this ragged gargantuan behemoth which had in the meanwhile also been amended by one of the senior programmers.

To my shame and horror, my killer code had been replaced by the longer-winded but cleaner-looking and much more easily-recognisable "traditional" version. Worse, the comment now read “Convoluted Coding Clouds Clarity”. Touche-bloody-A! It stung my pride at the time but taught me a valuable lesson not found in many books.

---

[1] Ah yes, now I remember, it was the day after I got the pay rise and promotion... :)

[2] “core” is the very old abbreviation for magnetic core memory