Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: change JavaDoc guildelines so that JavaDoc is not required for every element

...

  1. Two-space indenting The Sun coding convention suggests 4 space indenting; however with 80-column lines and four-space indenting, there is very little room left for code. Thus, we recommend using 2 space indenting. There are to be no tabs in the source files or trailing white space on any line.
  2. 132 column lines in exceptional cases The Sun coding convention is that lines be no longer than 80 columns. Several Jikes RVM contributors have found this constraining. Therefore, we allow 132 column lines for exceptional cases, such as to avoid bad line breaks.
  3. if (VM.VerifyAssertions) As a special case, the condition if (VM.VerifyAssertions) is usually immediately followed by the call to VM._assert(), with a single space substituting for the normal newline-and-indentation. There's See the coding conventions for an example elsewhere in this document.
  4. Capitalized fields Under the Sun coding conventions, and as specified in The Java Language Specification, Second Edition, the names of fields begin with a lowercase letter. (The only exception they give is for some final static constants, which have names ALL_IN_CAPITAL_LETTERS, with underscores separating them.) That convention reserves IdentifiersBeginningWithACapitalLetterFollowedByMixedCase for the names of classes and interfaces. However, most of the final fields in the Configuration class and the Properties interface also are in that format. Since the VM class inherits fields from both Properties and Configuration, that's how we get VM.VerifyAssertions, etc.

...

All files should contain descriptive comments in Javadoc™ form so that documentation can be generated automatically. Of course, additional non-Javadoc source code comments should appear as appropriate.

  1. All classes and methods

    Classes, methods and fields should have a block comment describing them

    All methods contain

    if it makes sense. There is no need to add comments merely for the sake of commenting. For example, it is not necessary to add a comment for a method if the comment does not provide more information than the signature and the method name already do.

  2. JavaDoc comments must not be copied from methods that are being overriden. If the comment from the method that you are overriding is sufficient, you do not need to provide JavaDoc for the newly added method - JavaDoc will automatically copy the JavaDoc from the overriden method. If you want to extend the comment from the overriden method with new information, use {@inheritDoc} to copy the comment from the superclass and add your text.

  3. JavaDoc for methods contains a short description of their arguments (using @param), the return value (using @return) and the exceptions they may throw (using @throws).

  4. Each class should include @see and @link references as appropriate.