Win a copy of Kotlin Cookbook this week in the Kotlin forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Bear Bibeault
  • Paul Clapham
  • Jeanne Boyarsky
Sheriffs:
  • Junilu Lacar
  • Knute Snortum
  • Henry Wong
Saloon Keepers:
  • Ron McLeod
  • Tim Moores
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
Bartenders:
  • Frits Walraven
  • Joe Ess
  • salvin francis

Are you a Javadoc Nazi

 
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..
 
Ranch Hand
Posts: 153
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I am not. But, my Tech Lead is :<(
 
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.
 
Wanderer
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.)
 
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
 
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
 
Bartender
Posts: 4121
IntelliJ IDE Spring Java
  • 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).]
 
A sonic boom would certainly ruin a giant souffle. But this tiny ad would protect it:
Java file APIs (DOC, XLS, PDF, and many more)
https://products.aspose.com/total/java
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!