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.

2 responses to “Javadoc Clutter”

  1. Ben Fulton says:

    But combining the big project picture with the class-level comments often provides useful information

  2. Ed Gibbs says:

    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.