Take Code Documentation Seriously

This is a classic one, every developer knows it, many ignore it, still it's one of the most important points to respect when the goal is to keep code maintainable: code documentation. At the university where I studied the instructors kept telling us one phrase very, very frequently:

A code without documentation isn't a code.

What can I say? It's true.

I have joined many projects where the application has already been released into production and where the initial developer team has left long ago. Usually these early developers on a project code in "freestyle mode" because there's high attention and pressure from the management side and the application has to be released as fast as possible. Documentation costs time and often is the first to be dropped in order to safe time in this phase. The second thing to be dropped are automatic tests. This works surprisingly well at the beginning when everything is small and neat - the problems start later when the code base has grown and has to be run and maintained by often other developers.

The combination of missing documentation and tests together with often enough messy code can really break your neck (and motivation): you basically have to find out things by yourself by analysing the code, trying to understand the aims and thoughts of the developers or sometimes even by guessing because the intention is simply not clear. This can be a tough, frustrating process and can cost a lot of time and money.

On the other hand over the recent years the expressiveness of code has increased a lot with e.g. fluent interfaces becoming very popular. Still there are aspects which cannot be expressed well or not at all through statements. Therefore, since we are all friendly developers and want that our fellow developers enjoy their work as much as we do:

Take code documentation seriously!

It's also about having respect for all those who follow and have to deal with your code later on. No one wants to stay in a house which is filthy, completely filled with broken furniture and house appliances, garbage lying around all over the place. Sad enough that many developers treat their code exactly like that. Documentation is one essential part of taking care for the code and leaving the 'house' tidied up.

My personal top 5 for doing proper code documentation are:

1. Keep the technical documentation close to the code.
   Developers work with the code and the IDE every day, so it's just natural to store as much documentation as possible inside the repo so that developers have it at hand for adaption directly when something in the code has changed. This also gives the nice side effect of commit history, traceability of changes and so on. For documentation directly inside the source code like Javadoc this is obvious but often there are other documents like e.g. architectural diagrams, data models etc. Putting these into a Wiki does not work. Why? Because at one point developers will stop keeping the Wiki pages in sync with the actual code (see point 4).

2. Keep it short and to the point.
   Writing lengthy texts is boring. Reading lengthy texts is boring. Focus on the essentials.

3. Don't be Captain Obvious.
   Documenting the obvious is a waste of time for both writers and readers. Focus on the unclear and implicit things which are not visible at the first sight. Focus more on why and less on what. In doubt: Look at the code as if you're new to the project and have never seen it before: What is missing in order to understand what's going on? What is unclear?

4. Misleading documentation is worse than no documentation.
   Before writing nonsense into a comment, it's better to skip it altogether. This also implies that if you refer to a certain aspect of the code in a comment, you have to keep it in sync when the code changes. Everything else is misleading.

5. Use proper spelling, grammar and punctuation.
   The majority of developers is not dyslexic. All modern IDEs have automatic grammar and spell checking integrated and making use of it costs almost zero effort. When you open a class and the class comment is packed with typos and grammar errors, all of them clearly marked by the IDE, what can you expect from the class?