tags:

views:

2441

answers:

16

Should I be writing Doc Comments for all of my java methods?

+14  A: 

I thorougly document every public method in every API class. Classes which have public members but which are not intended for external consumption are prominently marked in the class javadoc. I also document every protected method in every API class, though to a lesser extent. This goes on the idea that any developer who is extending an API class will already have a fair concept of what's going on.

Finally, I will occasionally document private and package private methods for my own benefit. Any method or field that I think needs some explanation in its usage will receive documentation, regardless of its visibility.

Daniel Spiewak
"I will occasionally document private and package private methods for my own benefit". This is fine if you are the only person who is ever going to look at the code, but not otherwise.
DJClayworth
I don't think this answers the question. It only describes what you normally do. I would like to know why.
Bno
+8  A: 

If the method is, obviously self evident, I might skip a javadoc comment.

Comments like

/** Does Foo */
 void doFoo();

Really aren't that useful. (Overly simplistic example, but you get the idea)

tunaranch
Accessors and mutators are another good example of this principle.
Daniel Spiewak
Accessors and mutators may need comments like/** Users first name. Does not contains symbols other than a-z,A-z and is not greater than 50 characters*/String getFirstName();/** Sets price. Should be positive, precision is reduced to 4 digits after decimal point**/void setPrice(double price);
Pavel Feldman
+8  A: 

[VonC: I just changed my answer in a community wiki one in order to synthesize the best of the other answers and allow you to choose this one -- community meaning I am not here for the karma: choosing this one will not get me any rep' points -- Edit it to make it better]

@Claudiu

When I write code that others will use - Yes. Every method that somebody else can use (any public method) should have a javadoc at least stating its obvious purpose.

@Daniel Spiewak

I thoroughly document every public method in every API class. Classes which have public members but which are not intended for external consumption are prominently marked in the class javadoc. I also document every protected method in every API class, though to a lesser extent. This goes on the idea that any developer who is extending an API class will already have a fair concept of what's going on.

Finally, I will occasionally document private and package private methods for my own benefit. Any method or field that I think needs some explanation in its usage will receive documentation, regardless of its visibility.

@Paul de Vrieze

For things, like trivial getters and setters, share the comment between then and describe the purpose of the property, not of the getter/setter

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

And yes, this is more work.

@VonC

When you break a huge complex method (because of high cyclomatic complexity reason) into:

  • one public method calling
  • several private methods which represent internal steps of the public one

, it is very useful to javadoc the private methods as well, even though that documentation will not be visible in the javadoc API files.
Still, it allows you to remember more easily the precise nature of the different steps of your complex algorithm.

And remember: limit values or boundary conditions should be part of your javadoc as well.

Plus, javadoc is way better than simple "//comment":

  • It is recognized by IDE and used to display a pop-up when you move your cursor on top of one of your - javadoc-ed - function. For instance, a constant - that is private static final variable -, should have a javadoc, especially when its value is not trivial. Case in point: regexp (its javadoc should includes the regexp in its non-escaped form, what is purpose is and a literal example matched by the regexp)
  • It can be parsed by external tools (like xdoclet)

@Domci

For me, if somebody will see it or not doesn't matter - it's not likely I'll know what some obscure piece of code I wrote does after a couple of months. [...]
In short, comment logic, not syntax, and do it only once, on a proper place.

@Miguel Ping

In order to comment something, you have to understand it first. When you trying to comment a function, you are actually thinking of what the method/function/class does, and this makes you be more specific and clear in your javadoc, which in turn makes you write more clear and concise code, which is good.

VonC
+1  A: 

simply put: YES

The time you need to think about whether you should write a doc, is better invested in writing a doc.

Writing a one-liner is better than spending time for not documenting the method at all in the end.

FunnyBoy
A: 

at a previous company, we used to use the jalopy code formatter with eclipse. That would add javadoc to all the methods including private.

It made life difficult to document setters and getters. But what the heck. You have to do it -- you do it. That made me learn some macro functionality with XEmacs :-) You can automate it even further by writing a java parser and commenter like ANTLR creator did several years ago :-)

currently, I document all public methods and anything more than 10 lines.

anjanb
I think he's referring to actually authoring documentation comments and not just putting in useless @param foo stuff with no substance (which is worse than no javadoc at all)
davetron5000
+5  A: 

When I write code for myself - NO. In this case, java doccing is a waste of my time.

When I write code that others will use - Yes. Every method that somebody else can use (any public method) should have a java doc at least stating its obvious purpose. For a good test - run the javadoc creation utility on your code (I forget the exact command line now). Browse through the webpage it generates. If you would be satisfied using a library with that level of documentation, you're golden. If not, Write more javadocs in your code.

Claudiu
I disagree, I actually find that comments often save me time and effort when I come back to a project 6 months later.
James McMahon
I sooo disagree with the first part of this answer! And I do completely agree with nemo comment
VonC
I just proposed to the author of the question to *not* choose your answer and choose my 'community-wiki' (no rep' points) summary answer instead. If that happens, let me know: I will upvote two of your other answers I find interesting ;) -15 + 20, you will not loose any points!
VonC
nemo and VonC -- he didn't say that he didn't document code for himself, only that he didn't javadoc it. That's kind of what I do.
gnud
i definitely write comments. it is incredibly useful. however, i find the javadoc style way too cumbersome, leading to way too much green between my code, making it hard to read. so javadoccing I leave for code others will use. for myself, just simple // comments will do!
Claudiu
I still disagree. Javadoc is an old cumbersome format, I grant you that. But it is recognized by IDE and allow that documentation to pop-up when you are using one of your own function elsewhere in your code. simple "//comment" is *not* a good solution.
VonC
+1  A: 

I feel there should at least be comments regarding the parameters accepted and return types in term of what they are.
One can skip the implementation details in case the function names describes it completely, for eg, sendEmail(..);

Nrj
+7  A: 

For things, like trivial getters and setters, share the comment between then and describe the purpose of the property, not of the getter/setter.

/** 
 * Get foo
 * @return The value of the foo property
 */
int getFoo() {
  return foo;
}

Is not useful. Better do something like:

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

And yes, this is more work.

Paul de Vrieze
Right on! Provided that bla is public. You do not want reference to *internal* algos in your public javadoc.
VonC
The user needs to know about bla in order to set foo meaningfully. To that extent bla is public, even if the user cannot modify any other data associated with it.
DJClayworth
+4  A: 

All bases covered by others already; one additional note:

If you find yourself doing this:

/**
 * This method currently launches the blaardh into the bleeyrg.
 */
void execute() { ... }

Consider changing it into this:

void launchBlaardhIntoBleeyrg() { ... }

This may seem a bit obvious, but in many cases the opportunity is easy to miss in your own code.

Finally keep in mind that the change is not always wanted; for instance the behaviour of the method may be expected to evolve over time (note the word "currently" in the JavaDoc).

volley
A: 

I try to at the very least document every public and interface property and method, so that people calling into my code know what things are. I also try to comment as much as possible in line as well for maintenance sake. Even 'personal' projects I do on my own time just for myself, I try to javadoc just because I might shelf it for a year and come back to it later.

I've been coding professionally for over 8 years now, and I can't stand having to pick up someone elses code after they quit or no longer work there, and have to figure out what it does with no docs. Most of my comments are for the benefit of anyone who might have to touch it later.

rally25rs
+2  A: 

For me, if somebody will see it or not doesn't matter - it's not likely I'll know what some obscure piece of code I wrote does after a couple of months. There are a few guidelines:

  1. APIs, framework classes, and internal reusable static methods should be commented thoroughly.

  2. Logic in every complicated piece of code should be explained on two places - general logic in javadoc, and logic for each meaningful part of code in it's own comment.

  3. Model properties should be commented if they're not obvious. For example, no point in commenting username and password, but type should at least have a comment which says what are possible values for type.

  4. I don't document getters, setters, or anything done "by the book". If the team has a standard way of creating forms, adapters, controllers, facades... I don't document them, since there's no point if all adapters are the same and have a set of standard methods. Anyone familiar with framework will know what they're for - assuming that the framework philosophy and way of working with it is documented somewhere. In this cases, comments mean additional clutter and have no purpose. There are exceptions to this when class does something non-standard - then short comment is useful. Also, even if I'm creating form in a standard way, I like to divide parts of the form with short comments which divide the code into several parts, for example "billing address starts here".

In short, comment logic, not syntax, and do it only once, on a proper place.

Domchi
Your answer has some good points in it in my opinion. +1. And I have referenced it in my "community-wiki-summary" answer
VonC
+5  A: 

There is another reason you should use javadocs. In order to comment something, you have to understand it first. When you trying to comment a function, you are actually thinking of what the method/function/class does, and this makes you be more specific and clear in your javadoc, which in turn makes you write more clear and concise code, which is good.

Miguel Ping
A: 

I make it a point to write javadoc comments whenever it is non-trivial, Writing javadoc comments when using an IDE like eclipse or netbeans isn't that troublesome. Besides, when you write a javadoc comment, you are being forced to think about not just what the method does, but what the method does exactly, and the assumptions you've made.

Another reason is that once you've understood your code and refactored it, the javadoc allows you to forget about what it does since you can always refer to it. I'm not advocating purposely forgetting what your methods do but it's just that I prefer to remember other things which are more important.

blizpasta
A: 

You can run javadoc against code that does not have javadoc comments and it will produce fairly useable javadocs if you give thoughtful names to your methods and parameters.

Paul Croarkin
A: 

It should have more clarity

+1  A: 

You should probably be documenting all of your methods really. Most important are public API methods (especially published API methods). Private methods are sometimes not documented, although I think they should be, just for clarity - same goes with protected methods. Your comments should be informative, and not just reiterate what the code does.

If a method is particularly complex, it is advised that you document it. Some people believe that code should be written clearly so that it doesn't require comments. However, this is not always possible, so comments should be used in these cases.

You can automate the generation of Javadoc comments for getters/setters from Eclipse via the code templates to save on the amount of documentation you have to write. another tip is to use the @{$inheritDoc} to prevent duplication of code comments between interfaces and implementation classes.

Jon