Self-Documenting Code is a Nonsense

Self-Documenting Code is a Nonsense

I made a statement in a recent article that “there is no such thing as self-documented code”. Clearly this is untrue - after all, it has it’s own Wikipedia page. Despite this, I strongly believe that self-documenting code is a nonsense.

Your software is a story and documentation is the rationale

O Romeo, Romeo, wherefore art thou Romeo?

When I was at school, I was that annoying kid who quite liked Shakespeare. It’s not my fault; I had a teacher who believed that plays should be acted, not read. She’d get us up acting out scenes and were some of my favourite lessons. We were also lucky enough that my school had bought Shakespeare books that actually explined the text - the left page was an explanation, the right page was the script. It taught us the context of much of Shakespeare’s words and their real meaning, especially that the above quote isn’t “oi Romeo, where are you?”

This is similar to coding. When I write some software, I’ll have certain things in mind at the time - what’s it’s purpose, what do I know about it’s usage, will this be used elsewhere. No matter what I do, when I come back to it in the future, I’ll be thinking different thinkgs - I’ll have learn more about my profession, I won’t have the same detailed knowledge I had when I wrote it. This is compounded if I approach something that I wrote many years ago or if it wasn’t me who wrote it.

Here, your comments should be a note of the assumptions you made when writing it.

Comments don’t just tell you what it does, but how it works too

I have a short memory. All too often, I’ll ask my wife where something is in the kitchen that she told me 10 minutes before. Each day, I may write hundreds or thousands of lines of code and I don’t remember each one. If I’ve been a good developer, I’ll have written my code as reusable classes which it’s likely there will be different configuration parameters that I can use.

What’s the probability of someone remembering the full usage of each method they write? For me, it’s small and that diminishes with time. And that assumes it’s the original author who’s always using it. If there are multiple developers, you have to tell them how to use it.

Sure, the unit tests can be used as a guide. But they can be mahussive. Far easier just to stick a note in saying how it should be used.

The people who claim their code is self-documenting are often the less experienced developers

This is a contentious one. As a scientist, I don’t like to say things that I can’t back up with good evidence. For that reason, I’m only going to talk about experience rather than talent. Experience is quantifiable, talent is subjective. And, by experience, I don’t just mean length of time they have been a developer, but the number of different pieces of software they have worked on (I consider a year 2 developer who’s worked on many pieces of software more experienced than someone in the same project for a decade).

In my experience, there appears to be a correlation between the people who don’t write documentation and the length of time they have been a software developer. There might be many reasons for this. They may know the software intricately, especially if they’re worked on it exclusively for many years. They may not have the length of time as a developer needed to come back to something after a couple of years and think “how did this piece of shit I wrote ever work?”

When I started out, I was that guy. I had the arrogance of youth. I knew that I would always be able to remember what it did. Hey, if I didn’t, I had my SVN commits (yeah, I’m old) to look back on. Of course, I didn’t know that I’d eventually forget things and that my commit messages of “stuff done” aren’t exactly illuminating.

Writing good comments

This is definitely subjective. You are writing to people in the future. You may not know these people, you certainly don’t know what they know.

  1. Your method names should be short and descriptive.
  2. Each method should have a statement about what you’re trying to achieve, what parameters it takes and what it returns. Most languages have some equivalent of JSDoc or Javadoc which can be extracted into full documentation.
  3. At if statements, branches etc, describe what’s going on. Yes, it’s usually obvious, but a single line hurts no-one.
  4. Each file should have an overall description as to it’s purpose, when it might be used and how. Again, use JSDoc/Javadoc if you can.
  5. If you revisit something and it’s unclear, add to the existing documentation when you figure it out.

I’m by no means perfect at this. I still look back at things and think “WTF?” Ultimately, I’ve paid the price over my career. I’ve had to rewrite whole swathes of my code because I’ve forgotten how it worked.

Don’t be like me. Be like how I want to be.