Comment Conventions

What follows is the lead comment before even the package that gives copyright info and
optionally version history.

/*
 * @(#)StringComparator.java        1.1 2008-04-13
 *
 * Summary: Compares two Strings, case-sensitive.
 *
 * Copyright: (c) 2009-2017 Roedy Green, Canadian Mind Products, http://mindprod.com
 *
 * Licence: This software may be copied and used freely for any purpose but military.
 *
 * Created with: JetBrains IntelliJ IDEA IDE http://www.jetbrains.com/idea/
 *
 * Version History:
 * - 1.0 2002-05-21 initial version
 * - 1.1 2009-04-13 add comments
 */
package com.mindprod.comparators;

...

/*
 * A multi-line forest type comment, separated after by a blank line.
 * Eclipse will reformat your comments. You need blank
 * lines embedded in them to prevent coalescing. Line breaks will not
 * be preserved.  I repeat, use blank lines, not new lines
 * to group items!
 *
 * Eclipse will not reflow this sentence into the preceding text,
 * because of the preceding blank line.
 */

a = b;

/* a comment about the following line. One blank line before, none after. */
c = d;

e = f;
// a detail comment about the preceding line. One blank line after, none before.

g = h; // a detail comment about this line

// a block or "proc-out" comment to temporarily hide some code
//
// reallyDeleteAllTheFiles();
// System.exit( 0 );

/* an embedded comment about a parameter */
String s = buildHeader( null /* without ads */ );

Same Javadoc follows, slash star star. It is highly structured, and may
include HTML tags.  It contains information for clients extracted into
HTML Javadoc.  Do not include implementation trivia or version history.
Make sure you use entities for < and >.

/**
 * Compare two MaxiFD objects by timestamp, dirNodes, fileWords,
 * and extension.
 *
 * @param a first MaxiFD object to be compared
 *
 * @param b second MaxiFD object to be compared
 *
 * @return +1 if a&gt;b, 0 if a=b, -1 if a&lt;b
 */
public final int compare ( MaxiFD a, MaxiFD b );

If you are using CVS or Subversion, you put special comments at the head
of your source file, and your version control system will fill in the
details of the current version and the version history.

/*
 * @version $Revision$
 * ID: $Id$
 * Revision History:
 * $Log$
 * ... and so on with other tags ...
 */