The Most Superfluous JavaDoc Comment
One of my favorites is:
/**
* Sets the value of the color property.
*
* @param value
* allowed object is
* {@link String }
*
*/
public void setColor(String value) {
this.color = value;
}
Without the valuable hint: "
allowed object is {@link String }" it would be hardly possible to find out how to invoke this method :-).
What are your favorites?
/**
* Gets the value of the color property.
*
* @returns {@link String }
*
*/
public String getColor() {
this.color;
}
Posted by Patrick on July 24, 2011 at 01:11 PM CEST #
//When I wrote this, only God and I understood what I was doing
//Now, God only knows
From http://stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered/482129
Posted by Markus on July 24, 2011 at 01:44 PM CEST #
/**
* Default constructor.
*/
public SomeClass() {}
Posted by Miggel on July 24, 2011 at 01:51 PM CEST #
This is why I delete all Eclipse generated javadoc if I don't want to write anything more.
Generated javadoc is only a template, nothing more. It should be edited or deleted, otherwise it is only hacking the Checkstyle plugin.
Writing a javadoc is boring, but not writing it is evil and you will get punched for every javadoc which wasn't written.
I can partially tolerate a bad javadoc in an application, but in a library it is really critical.
And one thing more - when I write a javadoc, sometimes I think of something important, what I forgot during the implementation.
Posted by dmatej on July 24, 2011 at 02:27 PM CEST #
@DMatej,
my thoughts about javadoc (ing): http://www.adam-bien.com/roller/abien/entry/how_to_javadoc_efficient_and
"I can partially tolerate a bad javadoc in an application, but in a library it is really critical."
I do not. IMHO it is better to delete redundant information, than keep it.
You should only comment non-obvious things.
thanks for your comment :-)!,
adam
Posted by Adam Bien on July 24, 2011 at 02:32 PM CEST #
Don't you think return type should also be described? In case "void" is not obvious enough...
Posted by Tomek N. on July 24, 2011 at 02:37 PM CEST #
I would completely remove JavaDoc from getters/setters because it's too much work for no benefit at all. JavaDoc for a setter e.g. would be only reasonable if the setter is doing more than just setting a particular value :)
Posted by Eduard Tudenhöfner on July 25, 2011 at 01:16 AM CEST #
" JavaDoc for a setter e.g. would be only reasonable
if the setter is doing more than just setting a particular value :)"
But if the setter is doing more than just setting the value one could argue that it is not a setter any more. So you can safely delete the JavaDoc from your setters as well :-)
thanks!,
adam
Posted by Adam Bien on July 25, 2011 at 01:20 AM CEST #
Agree. Setters and getters are just simple JavaBean property accessors. No need to document them. Anything else ... would probably need a word or two. So those are the ones to think about documenting.
( //move one step further
i++;
Now that's my favorite
)
Posted by Michael Willer on July 25, 2011 at 02:37 AM CEST #
/**
* This default constructor is generated by VisualAge.
*/
public Foo() {
}
Posted by Weiqi Gao on July 25, 2011 at 08:38 AM CEST #
I once seen the pattern to document either the getter or the setter with the meaning of the related property, but IMO this should be better placed at the class documentation...
Much more important than documenting obvious methods is to place useful in-line code comments. Once you accept that its necessary to read the code to really understand what its doing (and to change / extend it) it is obvious that these comments can be really helpful.
Finally I would like to ask for your opinion about a useful set of standard documenting (and maybe not only documenting) annotations you use. I often use @Immutable, @ThreadSafe. For JEE 5/6 it may make sense to define stereotypes like @Boundary and @Service. Any other suggestions?
@Adam: Thx for sharing your thouhts on code documentation!
Jan
Posted by Jan Wiemer on July 25, 2011 at 10:13 AM CEST #
This just reminds me of that one: http://geekandpoke.typepad.com/geekandpoke/2011/02/the-real-coder.html ;)
Posted by Alex on July 25, 2011 at 12:50 PM CEST #
I agree with you that it's not a setter anymore :)
But very often I have seen setter names that were doing much more than their names were promising. This might as well be some form of misuse :)
Back to the topic...I would say that JavaDoc for setter/getter is really unnecessary...we spend too much time adding/generating them just to satisfy our static code analysis tools :)
Thus a JavaDoc would only be reasonable here it it's not obvious.
Posted by Eduard Tudenhoefner on July 25, 2011 at 01:07 PM CEST #
/*
* Created on Jul 2, 2008
*
* TODO To change the template for this generated file go to
* Window - Preferences - Java - Code Style - Code Templates
*/
package de.mycorp.myapp;
And no one in the project cares.
That leads to "no one reads comments anymore", because it's spam all over the codebase.
Posted by Peter on July 25, 2011 at 02:06 PM CEST #
This was the ONLY comment in a system for analyzing SNMP traps, it included code in C++, XML and XSLT files which during compilation produced more C++ classes
// argc is the number of arguments, argv is the arguments
int main( int argc, const char* argv[] )
Good thing they bothered to explain that
Posted by Sigal on July 26, 2011 at 11:25 PM CEST #
I guess you know JAutodoc? http://jautodoc.sourceforge.net/
Best of it: People love it: "Great! Exactly what I was looking for", "Cool! Smarter than I expected" - Man, what did you expect?
Posted by Marcel on July 27, 2011 at 11:55 AM CEST #
Maybe a bit off-topic, but this "misdocumentation"actually is a methology in a lot of companies: Parameters may not be null, but because if there is an Exception from YOUR code YOU will be the first assignee in a bug you protect yourself and let the caller step into the NPE trap :-).
/**
* @param myParam not null.
* @returns result or null
*/
public String fooBar(String myParam) {
String result = null;
if(param != null) {
... // indent as much as you like
}
return result;
}
Usually this is not unit-tested either by caller or callee...
Posted by Peter on July 27, 2011 at 06:42 PM CEST #
This is a very old post, but I just wanted to add my ARS0.02:
I agree that documenting a simple getter/setter is useless. However, consider a setter that checks for valid values (e.g. not null, number range, etc.), or a getter that returns a "special" value in some scenarios, that should be documented, even more for interfaces. Of course, that falls in the "document the non obvious" category.
Posted by Alied on September 26, 2013 at 10:53 PM CEST #