Some Highly Opinionated Notes on Java Commentary

gistfile1.txt

	Some Higly Opinionated Notes on Java Commentary

Package Javadoc (package-info.java):
- Do this.  Help us understand how the classes in this package are
  related and where we should start in trying to learn them.
- Explain why these classes are packaged together.

Class/interface Javadoc:
- Omit "this class" etc.  We know it's a class.
- Classes and interfaces do not do things; they represent things.
  What real-world or business object does this class model?  (Utility
  classes and main classes are exceptions.)

Method Javadoc:
- Omit "this method" etc.
- Say what the method accomplishes, not what it does.
- Always say what a thrown exception means.  Say "passed through" if
  it's not yours and you don't know.
- Don't say how the method does its job unless you think this would be
  relevant to someone using the method elsewhere.  "How" might change.
- Don't refer to parameters' types since they may change:
  @param special_features user's postal addresses
  not
  @param special_features LinkedList of user's postal addresses
  Remember that the standard doclet will show the parameter's actual
  type from its declaration.

Code comments:
- Explain anything clever or obscure, but keep it brief.
- Tell us what you were thinking.  We can see what you wrote.
- Say what is accomplished, not what is done.

General:
- Use HTML elements to compose lists and tables.  The standard doclet
  will turn your ASCII-art attempts into gibberish and collapse all of
  your careful spacing.  IDEs will do the same.  Just because it looks
  right in the editor, does not mean it will be intelligible after
  processing. 
- Consider the definition list (<dl>...</dl>) for defining enumerated
  values.
- Use {@code blabla} in preference to <code>blabla</code>.