Alan Lee's List: javadoc api

• Four spaces
• Tabs must be set exactly every 8 spaces
• Avoid lines longer than 80 characters
• no more than 70 characters
• Example
• Align the new line with the beginning of the expression at the same level on the previous line.
• indent 8 spaces instead.
• Line wrapping for   if statements should generally use the 8-space rule

6 more annotations...

• grouped by functionality rather than by scope or accessibility

• A single-line comment should be preceded by a blank line.
• shifted far enough to separate them from the statements
• It shouldn't be used on consecutive multiple lines for text comments
• Members, including constructors, have 4 spaces for the first doc comment line and 5 spaces thereafter.
• 1 space of indentation

3 more annotations...

• One declaration per line
• initialize local variables where they're declared
• Put declarations only at the beginning of blocks.
• one exception to the rule is indexes of   for loops
• No space between a method name and the parenthesis
• Open brace "{" appears at the end of the same line as the declaration statement
• Closing brace "}" starts a line by itself indented
• Methods are separated by a blank line

6 more annotations...

• opening brace should be at the end of the line that begins the compound statemen
• if statements always use braces {}
• avoid the complexity of using more than three variables
• Every time a case falls through (doesn't include a   break statement), add a comment
• Every   switch statement should include a default case.

3 more annotations...

• Two blank lines
• One blank line
• A keyword followed by a parenthesis should be separated by a space.
• A blank space should appear after commas in argument lists.
• All binary operators except   . should be separated from their operands by spaces.
• Casts should be followed by a blank space.

4 more annotations...

• nouns
• Use whole words-avoid acronyms
• Variable names should not start with underscore _ or dollar sign $ characters

1 more annotation...

• Numerical constants (literals) should not be coded directly
• Do not use embedded assignments
• return (condition ? x : y);
• Use   FIXME to flag something that is bogus and broken.
• Use   XXX in a comment to flag something that is bogus but works.

3 more annotations...

• The specification should describe (textually) the thread-safety guarantees provided by a given object. In the absence of explicit indication to the contrary, all objects are assumed to be "thread-safe"
• The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the API item.
• Write the description to be implementation-independent
• mention what the specification leaves unspecified or allows to vary among implementations
• "On <platform>"
• "Implementation-Specific:"
• Use <code> style for keywords and names
• f referring to both forms of the method, omit the parentheses altogether
• Use 3rd person (descriptive) not 2nd person (prescriptive).
• Method descriptions begin with a verb phrase.
• Use "this" instead of "the" when referring to an object created from the current class.
• Avoid Latin
• multiple @see tags, can be separated from the other tags by a blank line with a single asterisk.
• @throws tags (also known as @exception) should be listed alphabetically by the exception names.   <!-- Multiple @throws tags should generally be listed alphabetically by the exception names. However, there may be times when it may be more sensible to group them primarily by inheritance and secondarily  alphabetically. For example, a method for reading a serialized  object from a file can throw a host of exceptions, including: <pre>  IOException  EOFException  FileNotFoundException  StreamCorruptedException </pre> <p> A client object interested merely in a simple success/failure of  such a method call can try/catch IOException alone. All the other  exceptions are subclasses of IOException. -->   
• @see tags should be ordered as follows
• from nearest to farthest access, from least-qualified to fully-qualified
• @param tag is "required"
• @return tag is required
• By convention, the first noun in the description is the data type of the parameter.
• The description begins with a lowercase letter if it is a phrase (contains no verb), or an uppercase letter if it is a sentence. End the phrase with a period only if another phrase or sentence follows it.
• document exceptions that are independent of the underlying implementation.
• package.html
• Copies its contents (everything between   <body> and   </body>) below the summary tables
• Copies the first sentence to the right-hand column of the     Overview Summary  .
• short, readable description of the facilities provided by the package
• purpose
• relationships
• conceptual framework
• Javadoc 1.2 looks for and copies to the destination directory a directory named "doc-files" in the source tree (one for each package) and its contents.
• Name GIF images   <class>-1.gif

28 more annotations...

• assumptions
• handling unchecked exceptions
• Specify any reliance on the underlying operating system or hardware.
• Specify the state information associated with the object

2 more annotations...