19

There is a copyright comment in each java file, but I don't know which one should I use: /* */ or /** */?

 /*
  * Copyright ...
  */
 import java.util.*
 ...

or 

/**
 * Copyright ...
 */
import java.util.*
....
user
  • 86,916
  • 18
  • 197
  • 190
Freewind
  • 193,756
  • 157
  • 432
  • 708

4 Answers4

12

This rather old (circa 1999) Sun coding conventions document suggests /* */.

More specifically, it suggests the following layout for your class/interface file(s):

  • Beginning comments

    /*
 * Classname
 * Version information
 * Date
 * Copyright notice
 */
  • package and import statements
  • Class and interface declarations (which includes Javadoc comments for the class - see table entry #1).

Example:

/*
 * MyClass
 *
 * v1.0
 *
 * 2011-11-29
 * 
 * This file is copyrighted in an awesome way.
 */
package com.example.mypackage;

import com.example.otherpackage;

/**
 * Javadoc comments for the class.
 */
public class MyClass {
    ...
}
banterCZ
  • 1,551
  • 1
  • 22
  • 37
Rob Hruska
  • 118,520
  • 32
  • 167
  • 192
10

Javadoc will only gather /** ... */ comments if they are directly before any declaration to be documented. package (other than in package-info.java) and import declarations are not documented anyway, so Javadoc will not look at the comment in either way.

As it doesn't matter for Javadoc, you can as well use the "less heavy" /* ... */ version.

Paŭlo Ebermann
  • 73,284
  • 20
  • 146
  • 210
  • 1
    +1 [Here's the documentation reference](http://docs.oracle.com/javase/6/docs/technotes/tools/windows/javadoc.html#comments) if you want to add it to your answer. Specifically the section **Placement of comments**, where it states: *"Documentation comments are recognized only when placed immediately before class, interface, constructor, method, or field declarations"*. It also sort of identifies the discussion on this question: *"A common mistake is to put an `import` statement between the class comment and the class declaration. Avoid this, as the Javadoc tool will ignore the class comment."* – Rob Hruska Nov 30 '11 at 15:58
6

If you use /** */ documenting tools will grab it so you're better off using it :)

Victor Parmar
  • 5,719
  • 6
  • 33
  • 36
  • 3
    Is that always the Right Thing, though? What if the copyright only applies to the code? What if the Javadoc API is licensed/copyrighted differently? – Rob Hruska Nov 30 '11 at 03:17
  • 2
    This is actually incorrect for the example code given in the question. See [Paŭlo's answer](http://stackoverflow.com/a/8323983/29995) and my comment on it. – Rob Hruska Nov 30 '11 at 16:00
  • 1
    Javadoc will not grab stuff before an import statement like in the example in the question. – Paŭlo Ebermann Nov 10 '15 at 19:25
4

I just read some open source java projects, found they all use /* */

Freewind
  • 193,756
  • 157
  • 432
  • 708