Home/ Questions/Q 1048617
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-05-16T16:29:10+00:00

When is it appropriate to use a block comment at the beginning of methods,

  • 0

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.

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    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.

    • 0