Documenting Code

It amazes me how often you see useless code documentation. By “useless”, I mean documentation that doesn’t add any information that isn’t already present in the type signatures.

Documentation like the following example is quite common in most codebases:

/**
 * Gets a person by id
 * @param personId person identifier
 * @return person with given id
 */
Person getPersonById(int personId) {
    ...
}

The only thing unclear from the type signature is what would happen if the person is not found. And in this case, that is not documented.

Searching IntelliJ Marketplace, I found that there are even plugins that will generate such Javadoc for you. I believe this bad practice comes from universities. When I went to university, we were told that every method should be documented.

My opinion is that if you feel the need to document your code, in a strongly typed language, then you should interpret that as a code smell. You can probably look for a better method name or a cleaner abstraction and leave out the documentation.

Written on April 27, 2020

Tags: