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:

1
2
3
4
5
6
7
8
9
/*
* 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.

2 comments to Javadoc Clutter

  • 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.