Win a copy of Functional Reactive Programming this week in the Other Languages forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Are you a Javadoc Nazi

 
Alok Pota
Ranch Hand
Posts: 185
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Are you a Javadoc Nazi?
I think Javadoc is good as long as it does not obfuscate code.I have seen code with a getter method preceded by several lines of
Javadoc..
 
Allan Moster
Ranch Hand
Posts: 153
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I am not. But, my Tech Lead is :<(
 
David Weitzman
Ranch Hand
Posts: 1365
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I want to be a javadoc nazi, but I'm a naturally lazy person. Fortunately one of the code beatufiers for JEdit can enforce them.
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Maybe it can enforce that there is something there, but I doubt it can force you to make the comments useful. I routinely see comments like:
<pre>
/**
* Constructor for MyClass
* @param str Input of constructor
* @exception IOException
*/
MyClass(String str) throws IOException {
...
}
</pre>
Well, duh. If a doc comment doesn't have anything to add to what javadoc can already derive from the declaration, there's really no point, and I don't want to spend time reading it. Somedays I'm tempted to measure my productivity by how many useless lines I can delete from a file - comments are often a big part of this.
Having said that, I'm I big believer in putting in detailed javadoc comments for things that aren't obvious. For get and set methods, the "get" and "set" parts may be obvious - but often what you do need is an explanation of what that property's role is in the class, and how it is used. Often this works better in the main class doc comment, since otherwise I can't decide whether to put it in the "get" comment or the "set" comment, and I hate putting the same info in two places. (D.R.Y.)
 
Badriprasad Bumbabol
Ranch Hand
Posts: 389
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Documentation is Over-rated. In fact,anything which involves work is over-rated
Dont flame me guys, its just the stress of working on the last 2 weekends, thats making me write this. Otherwise I am just a normal guy who likes Documentation(and work)
Tintin
 
Jim Bertorelli
Ranch Hand
Posts: 136
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
what the hell....if I spent an hour coding a routine, the guy who wants to modify it must spend 2 hours understandting it. Come on guys...that's job security
 
Nathan Pruett
Bartender
Posts: 4121
IntelliJ IDE Java Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
It's really amazing how good the Java API JavaDocs are... it's really noticeable when you get a third-party API and you have something like this declaration :



Now we get to play "Guess the category"!!!

-Nate
[This message has been edited by Nathan Pruett (edited December 05, 2001).]
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic