Javadoc comments vs block comments?

Question

When is it appropriate to use a block comment at the beginning of methods, and when is it appropriate to use a javadoc-style comment?

From the "Comments" section of the Java style guide, I found this:

Java programs can have two kinds of comments: implementation comments and documentation comments. Implementation comments are those found in C++, which are delimited by /*...*/, and //. Documentation comments (known as "doc comments") are Java-only, and are delimited by /**...*/. Doc comments can be extracted to HTML files using the javadoc tool.

Implementation comments are meant for commenting out code or for comments about the particular implementation. Doc comments are meant to describe the specification of the code, from an implementation-free perspective. to be read by developers who might not necessarily have the source code at hand.

So, another way to phrase my question would be: When do methods deserve a specification of the code, from an implementation-free perspective (Javadoc) instead of a comment about a particular implementation, and vice versa? Would an interface get javadoc comments, while the implementations get block comments?

edit: I think I am not conveying my question correctly, based on the answers thus far.

Here's an example of what I want to know.

/**
 * Javadoc comment here about general implementation?
 */
/*
 * Should I now have a separate block comment for my specific implementation?
 */
public void foo()
{
...
}

The two different comment styles convey two different types of information. Are there cases when methods should have BOTH a leading javadoc comment, and a leading block comment?

The inspiration for even asking is that Eclipse auto-generated this for me just now:

/*
 * (non-Javadoc)
 * @see my.package#process()
 */

And I figured there is some sort of styling going on here that isn't declared specifically in the comment specifications I link to above.

Answer 1

In my opinion, Javadoc comments are comments you write to the people who use your code, and who invoke your methods.

Javadoc comments are more focused on the parameters of the methods, what your method will return depending on the parameters you give to your methods.

Block comments are internal comments, comments you write for people maintaining your code.

Block comments are important to understand how the code works, why it works and which are the operations used to do the actual work.

Answer 2

Info that the user of a class needs to know should go into a Javadoc comment.

Info that a developer modifying a class needs to know go into a normal comment (block or line).

And it's very possible that any block of code (class, interface, field, method, constructor, ...) can have both a Javadoc comment and a normal comment block, when both publicly visible as well as internal documentaton is required.

Personally I tend towards writing very little non-Javadoc comments, because I prefer to structure my code in a way that it's self-documenting.

Answer 3

In my opinion it makes no sense to put block comments at the top of the method (well, never say never but at least most of the time). Javadoc comments on interface methods specify the contract, on class methods they tell about the implementation so a user can decide which class to use if there are multiple classes implementing a single interface. Think about the List interface; the implementations ArrayList and LinkedList are appropriate in different use cases so their respective documentations might explain about their pros and cons.

I inline block comments about very specific things. I want the implementation specific doc directly where the implementation is. Of course you should use them as rare as possible. Use expressive variable and method names and they automatically add low level documentation.

The automatically generated block comments of Eclipse are for you to fill out and potentially make them Javadoc comments by adding the missing asterisk. I don't know exactly in which cases they appear but one is when you extract an interface from an existing class. Then the Javadoc from the class goes to the interface method and the class method gets the block comment. The reasoning behind this is that often when implementing an interface you don't really have that much to add. Again I use List as an example. The size() method wouldn't need any more documentation in the ArrayList and LinkedList implementations. They have nothing of value to add. Of course this example is contrived because the actual implementations (at least of OpenJDK) do have Javadocs but I see no need for that and indeed the don't add anything of value. Worse yet they provide even less information than the interface documentation.