JavaDoc

A little while back I said duplicate code was the biggest codesmell I knew of. I was wrong. There is a level of smelly code that goes well beyond duplicated code, in fact it goes well beyond anything a professional programmer would ever do. That is the smell of code that doesn’t have JavaDoc comments. From time to time every programmer will get lazy and not bother to add a comment for something but every so often you come across a code base that seems to have a systematic policy of removing any JavaDoc comments that might prove useful. Sadly, I was reminded of this when attempting to use BCEL. Vast swaths of that project are completely devoid of JavaDoc comments. Maybe the functionality of those methods are completely obvious to anyone who’s ever touched the codebase, but I’m trying to work out how to use the library so I need to at the very least be told “this method is not for you – go away”. In the end I gave up and used ASM which is still fairly light on JavaDocs at times and quite often the JavaDocs that are there are too abrupt to be particularly useful but at least there’s something. All the same, the process of using ASM is essential a case of trial and error unfortunately. So if you ever teach anyone Java, beat into them how useful, powerful and important JavaDoc comments are. It doesn’t matter how neatly laid out your code is or how obvious the functionality may be – most people who go to reuse the code are going to look only at the JavaDocs either through the generated HTML or through their IDE. Make sure the information there is useful.