Why you should and should not write code documentation

(last update at ) — 1064 words

This article is part of a series:

Writing documentation Tips and tricks for writing documentation for code projects.
  1. Why you should and should not write code documentation
  2. Technical documentation writing quick tips
  3. Quick tip: Formatting unordered lists in plain text
  4. Remove hard line breaks from READMEs

The question of whether one should document their code is the subject of fierce discussions, not akin to the age-old debate about "tabs vs. spaces" (#TeamSpaces here). I'm in the camp of people who think that one should write documentation, but only for a good reason.

Below I will share some practical tips and philosophy regarding writing documentation. This article is not about judging practices as "good" or "bad," and I do not claim that my opinion is the absolute truth.

This article originally started as a tweet: https://twitter.com/MHLut/status/1025408074687950848

Side note: I still did not fix my blog, so tweet embedding is wonky.

Code should document itself; humans should document choices

Any programmer who has used a Version Control System (VCS) in a group setting recognizes this scenario: You've run into some bug or otherwise inexplicable piece of code, and you're wondering who wrote this abomination. Later, VCS blame reveals that you are the author of these lines or the one who approved them.

Forgot all about these monsters of your creation, have you? Awkward.

The best code is code that explains itself: clearly written, broken up into tiny pieces (think LEGO® blocks), using sensibly named variables, and generally something that does not instill you with rage. In short: code that needs no documentation on what it does.

If your code is good, people understand what it does when reading through it. If you need to explain to your fellow programmers that your function sums up two numbers and returns the result, that's a major red flag.

There is one thing people tend to forget, though: the effects of time, aging of code, legacy systems, new additions to developer teams, basically what happens when we move on after writing said code. It gets worse when people start asking questions about why you did what you did there.

When you write a piece of code, there will never be anyone who understands its intention better than you do right at that very moment.

So rather than documenting what your code does, document why it does whatever it does. Explain choices, caveats, refer to support tickets where needed, anything that explains to future readers what is going on.

Tips

Tip 1; Programmer sense:
As you become a seasoned programmer, you develop a sense of which information would be relevant for future reference and which is not. Feel free to ask someone else to review your code to see whether it makes sense; if you use pull requests, you can also ask reviewers to focus on specific parts.

Tip 2; Self-describing code:
Make code as self-describing as possible. Use type hints if your platform supports it, and use sensible naming. For example: use prefixes is_ and has_ for boolean variables, and a suffix _at for date/time values. Stay clear of abbreviations that your peers do not immediately understand.

Tip 3; Stick it where humans will read it:
You can write documentation in many places. Ideal places are class or function docs. If you do not have a function or class, add a big block of comments on top of the file. Remember that you write for humans and not a computer, so use human language and stick to a place where humans look for more information.

Tip 4; Explain your reasoning:
Describe why you chose one solution over another, especially when the alternative seems obvious. Such a statement should also deter future refactor-happy programmers from breaking your code.

It could be as simple as: We use <method y> here instead of <method x> like we normally would because <method x> breaks <some use-case>.

Addendum to tip 4; Unit tests:
Another way to prevent people from breaking code is to write unit tests. In a certain way, tests are also documentation, as you describe which behavior or results you expect from your code.

Tip 5; Some emotion is allowed:
If some code drives you up the wall, feel free to reflect on this in your comments. A former colleague had so many issues with a semi-functioning integration that he added a statement containing several mild expletives, which served as a warning to future developers.

Take note; you should not cuss in codebases you do not own.

Tip 6; No code left behind:
Do not comment blocks of code and leave them there as-is. It is best to delete them, but if you must keep them, at least note down why they've been disabled. If you're temporarily disabling something because you're waiting for a fix, add ticket numbers or other references to make this clear. Also, use a phrase like "ToDo" so you can find it again through code editor text search.

Tip 7; Keep it short:
Keep your documentation short and straightforward; otherwise, people will not read it. Try to avoid paragraphs longer than two lines with a maximum line length of eighty (80) characters, up to a maximum of four lines.

Tip 8; Do it as soon as possible:
I'm convinced that you cannot correctly document code after the fact. Write documentation as soon as possible after writing the code, when it's still there in your mind.

Bonus tip:
This one is more about code style than documentation. Try to avoid nesting big blocks of code, especially if you're going to nest more inside. As soon as you can, reverse an if-statement in your code and return from a function. Doing so makes code flow easier to follow.

Bad documentation is worse than no documentation

There is something about writing documentation that you need to keep in mind: you commit to it for the long run.

If you change a function or anything else in such a way that it no longer does "what it says on the tin," you must make sure to update all related docs. It is worse to have wrong information than no information at all. Do not add confusion to the mix.

Wrap-up

In short:

  • Write logic that does not need to have its inner workings explained, as that is a red flag for unmaintainable code.
  • Write documentation to explain choices, philosophy, anything not directly translatable from the code.
  • Documentation should be correct; otherwise, it becomes confusing.

Do future you and present/future others a favor and take this extra bit of effort (it should not be much effort even!) and write down all the things you'll have forgotten three months from now.