wood burning stoves*
The moose likes Meaningless Drivel and the fly likes Are you a Javadoc Nazi Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Murach's Java Servlets and JSP this week in the Servlets forum!
JavaRanch » Java Forums » Other » Meaningless Drivel
Bookmark "Are you a Javadoc Nazi" Watch "Are you a Javadoc Nazi" New topic
Author

Are you a Javadoc Nazi

Alok Pota
Ranch Hand

Joined: Mar 07, 2001
Posts: 185
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

Joined: Sep 14, 2001
Posts: 153
I am not. But, my Tech Lead is :<(
David Weitzman
Ranch Hand

Joined: Jul 27, 2001
Posts: 1365
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

Joined: Jan 30, 2000
Posts: 18671
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.)


"I'm not back." - Bill Harding, Twister
Badriprasad Bumbabol
Ranch Hand

Joined: Apr 19, 2001
Posts: 389
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

Joined: Nov 28, 2001
Posts: 136
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

Joined: Oct 18, 2000
Posts: 4121

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).]


-Nate
Write once, run anywhere, because there's nowhere to hide! - /. A.C.
 
permaculture playing cards
 
subject: Are you a Javadoc Nazi
 
Similar Threads
Thread execution
Question on getParameterNames and getParamaterValues return types
Creating an InputStream from a String
What does bufferedWriter.flush() and bufferedWriter.close() do?
Count duplicates in a TreeSet Collection