3. 2. J2EE Naming Conventions Rules

Appendix A - Conventions Rules

3. 4. Java Coding Conventions Rules

Java Comments Conventions Rules

Overview

Table A.3. Java Comments Conventions Overview

JAD_001: Do Not Use An Invalid Javadoc Comment Tag (High)

This rule verifies code against accidental use of improper Javadoc tags. Replace misspelled tags.

Note An exception to this rule are javadoc tags that are used by third party tools like, for example XDoclet or Together.

JAD_002: Provide A Correct File Comment For A File (High)

According to Sun coding conventions, all source files should begin with a C-style comment that lists the copyright notice and optionally the file name.

/*
 *
 * Copyright notice
 *
 */

This audit rule verifies whether the file begins with a C-style comment. It may optionally verify whether this comment contains the name of the top-level class the given file contains.

JAD_003: Provide A JavaDoc Comment For A Class (Enforced)

The JavaDoc comments for a class are missing

WRONG

public class Foo {
    // ...
}

RIGHT

/**
 * More information about the class.
 *
 * @author firstName lastName - companyName
 * @version 1.2.2 - 25/09/2003
 */
public class Foo {
    // ...
}

JAD_004: Provide A JavaDoc Comment For A Constructor (Enforced)

The JavaDoc comments for a constructor is missing.

WRONG

public class Foo {

    public Foo(char c) {
    }

    /**
     * More information about the method here
     */
    public boolean isValid() {
    }
}

RIGHT

public class Foo {

    /**
     * More information about the constructor here
     *
     * @param c the character to be tested
     */
    public Foo(char c) {
    }

    /**
     * More information about the method here
     *
     * @return <code>true</code> if the character is valid.
     */
    public boolean isValid() {
    }
}

JAD_005: Provide A JavaDoc Comment For A Method (Enforced)

The JavaDoc comments are missing for a method.

WRONG

public class Foo {

    public boolean isValid() {
        // ...
    }
}

RIGHT

public class Foo {

    /**
     * More information about the method here
     *
     * @return <code>true</code> if the character is valid.
     */
    public boolean isValid() {
        // ...
    }
}

JAD_007: Provide A JavaDoc comment For A Field (Enforced)

The JavaDoc comments for a public, friendly or protected field are missing

WRONG

public class Foo {

    public static final int FOO_CONSTANT = 1;
}

RIGHT

public class Foo {

    /**Foo constant value (set to 1)*/
    public static final int FOO_CONSTANT = 1;
}

JAD_008: Provide a package.html per package (Low)

Each package directory in the source file tree should have a package.html file. This file should provide a brief overview of the package's content.

3. 2. J2EE Naming Conventions Rules

Appendix A - Conventions Rules

3. 4. Java Coding Conventions Rules