Question

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

Answer 1

@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.