Javadoc Clutter
I once thought Javadoc was a great tool. I added an ant target for every project I built. Now it’s just clutter. I saw another example of the pain point of Javadoc again recently on an internal project that isn’t designed to ever be used as an API:
/*
* Returns Publisher when passed Id
*/
public Publisher getPublisherById(String id)
/*
* Returns Publisher when passed Id
*/
public Publisher getInstitutionById(String id)
Just drives me crazy the comments fall out of sync with the code as soon as someone performs a cut and paste. And the darn things can double the number of lines in a class, especially when you have a lot of short methods. (And you should have a lot of short methods.) Uggh.
But combining the big project picture with the class-level comments often provides useful information…
I see the other side of the argument, but in practice the time I’ve put into commenting hasn’t paid off. And worse yet the most common comments I see are out of sync even at the class level.
I do find some value in high level component diagrams or class diagrams of some critical classes. I realize if I spent time writing APIs Javadocs would be a lot more important, but I just don’t write APIs.