Code documentation, it can be tedious to write and maintain, what’s a developer to do?
I was asked for my advice on documentation today and realised just how much my approach had 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 taking the time to write quality code, also took the time to document it beautifully. I documented classes and methods religiously and sprinkled my code with helpful inline comments. These days I take a very different approach.
Sourcecode
The level of documentation needed for sourcecode really depends on who is consuming it. If you are writing a library which will be used by 3rd parties it may be appropriate to document your public interfaces and classes with explanations and usage examples. Your public methods may likewise be documented to contain useful information. That said, every comment is both a burden to write and to maintain and should therefore only be there if it adds legitimate value. Comments added for the sake of commenting are not only a waste of time but could in future fall out-of-date and become a point of confusion. This is especially common in projects drowning in superfluous documentation which developers soon learn to ignore. Anything which explains the obvious, repeats information or could be autogenerated should go so that all that is there is worthwhile. This approach saves time and creates a culture where developers know that if they see a comment is exists for a reason and it is important to take note of it and take care to maintain it.
What about internal documentation? The best documentation here is no documentation. Wherever 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?” This generally results in a code improvement.
Of course considered documentation can be genuinely useful. I sometimes add descriptions, links or references to methods implementing specialised algorithms. Anytime I implement a temporary workaround for a bug in an external component, I document it with a TODO and a link to the issue, to ensure that the workaround is removed once the issue is fixed. That said my internal documentation is kept to a minimum, inline comments are almost non-existent and the few TODOs are for issues that absolutely cannot be fixed right now.
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 which are separate to the code, get forgotten and go out-of-date quickly.
Tooling
Sourcecode: 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 come to the conclusion that it’s not the most feature-packed tools that are best, it’s the simplest ones that get the job done.
subsymbolic 