Finding the right level of documentation

Writing only meaningful documentation reduces confusion and leaves devs with more time to code. Use simple tools to get the job done.

I was asked for my thoughts on code documentation today and realised how much my approach has changed over the years. In my eager early days of development, I thought the mark of a true professional was someone who, in addition to writing quality code, also took the time to document it beautifully. I added block comments to classes and methods and sprinkled helpful inline comments throughout my code. These days, I take a very different approach.

Source code

The level of documentation needed depends on the audience consuming it. If you are writing a library which will be used by 3rd parties, it can be helpful to document your public interfaces and classes with explanations and usage examples. If your project is open source, you may add more documentation again, liberally documenting your methods, perhaps even the odd private ones that need explanation.

Remember, however, that each comment is a burden to write and maintain. It should therefore only exist if it adds legitimate value. Unnecessary comments are not only a waste of time but could fall out of date and become a point of confusion in the future. This is especially common in projects drowning in superfluous documentation that developers quickly learn to ignore. Anything explaining the obvious, repeating information or that can be autogenerated, should go so that everything left is worthwhile. This approach saves time and creates a culture where developers know that if they see a comment, it is there for a reason – they should take note, read it and maintain it.

What about internal documentation? The best internal documentation is light. Where possible, make your code self-documenting. Not only does this reduce your documentation overhead but it will produce better code. Anytime I’m tempted to write an inline explanation for some challenging section of code, I ask myself “How can I make what is happening here more obvious?” which generally results in a code improvement.

Of course, considered documentation can be genuinely useful. I often include descriptions, links or references to tricky code or methods implementing specialised algorithms. My internal documentation is kept to a minimum and my inline comments are rare, but they do exist.

Developer Guides

Sometimes developer guides such as a readme or an installation manual are needed. I keep these in source control with the code so they get updated as the project changes. If these documents need to be published elsewhere, e.g. on a website, I automate this as part of my build process. I prefer not to use static wiki pages stored separately from the code, which get forgotten and quickly become dated.

Tooling

Source code: I use whatever the industry standard for the language is. For example, I use Javadoc for Java and markup for Swift. By doing so I get great integration with my IDE, easy-to-use documentation which looks similar to the standard language docs and I know that any new developers to the project will be familiar with both the syntax and the style.

Developer guides: I generally use markdown. Markdown is simple, well-known and already something I need for 3rd party tools such as GitHub when creating readme files.

There was a time when I strived to find the “best” tool for everything. I am more relaxed about such things now. I’ve concluded that it’s not the most feature-packed tools that are best, it’s the simplest ones that get the job done.