How NOT to write Javadoc...

Last Update: 10.04.2018. By Jens in Developers Life | Learning | Newsletter

Today I am presenting you a case of Javadoc gone wrong; an actual live one, just saw it today, live and in color, in the project from the stone age.

Class Hotspot does have two id fields:

1. hbId
2. hsId

The Javadoc comments were:

1. The hb Id
2. *The hs id *

Wow, now I really understand it. Hurray. The wonderful comments made crystal clear what those ids are for…

The dev should be punished for that. Honestly.

There is a chance that the dev knew at the moment he wrote the comment what the meaning of those two id fields is. He should have written that. Write the comments for your future self of the poor guy having to maintain it after you. 6 month later you will have forgotten what the meaning of those two id fields is. Honestly, if there is only one id in a class, it’s clear that it is a unique identifier, even naming it contractId, personId or similar makes it clear. So, either name the field in the long form, whatever hs or hb stands for, or explain it in the javadoc comment.

Another example from the same codebase. A method parameter named id with the javadoc description The id. Yeah, I guessed so, because it is name id, but of what? The method signature or Javadoc did not make that clear.

So, let’s write docs rather for our future self than seeing it as an annoyance.