Self-documenting code is (mostly) nonsense

Your code isn’t as clear as you think it is, but there’s things you can do to help

Christopher Laine
IT Dead Inside
Published in
7 min readJun 16, 2019

--

Photo by rawpixel.com from Pexels

I just got through reading Cindy S Cheung’s great article on technical documentation and why devs need to explain their code better, and I have to say I completely agree.

I’ve been at this IT game a long bloody time, and in my experience, there is one self-delusion which developers and engineers just can’t help but cling to.

My code is self-documenting — The Delusional Dev

The theory here is that an engineer’s code is so clear, so easy to read, that is doesn’t require documentation.

Yeah, this is nonsense…mostly.

Why is ‘self-documenting code’ nonsense?

Look, you might be the Ernest Hemingway of programming. Your code might be super-duper clear and easy to read (to another dev). The fact remains that it IS code, and no matter how concise and clear your work might appear, it is not meant for non-programmers to access without a lot of squinting and muttering of “wtf does that mean?!”

So why is self-documenting code nonsense? Let me lay it down for you.

Reason 1: There are all kinds of gotchas in programming which do not self-document

Simply, because most people, including developers, are not machines. Yes, I can most likely muddle through your code, yes I can read your method and class names. I can even see what you’re doing in each method.

Code is written FOR machines. They know what the heck to do with it, and thus why we have programming languages. People, on the other hand, need a more human way of accessing what your software is doing.

Reading code and seeing what it does is a long way from documentation. It might have all the elements of what your code is doing, but are all those things…

--

--