CSC 102 Java Coding Conventions

  1. Follow the standard Java coding conventions defined at the Sun site 
    http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html,
    except where the remaining conventions in this document deviate for the Sun conventions.

  2. Define each public class in a separate .java file.

  3. Document .java files as follows, noting well the format of the comments, including the number and placement of *'s and the amount of indentation. 
    import ... ;

/****
 *
 * The comment at the top of a .java file is a high-level description of the
 * class defined in the file.  Start the description with the words "Class X"
 * and then describe the purpose of the class and the major methods it
 * provides.  The method descriptions in this header comment are generally
 * brief, e.g., "Class X provides methods to add, delete, change, and find
 * its elements."  Do not list all of the method details in the header
 * comment, since full comments for each method appear below in the body of
 * the class, at the site of each method declaration.  The header comment can
 * describe the data representation used in the class in high-level terms if
 * it's germane to explaining what the class is for.  The header comment does
 * not describe low-level details of the data representation or any details of
 * method implementation.
 *
 *
 * @author Name and current email address of file's author; name is at
 *         least first and last, with middle name or initial if necessary or
 *         commonly used by author; email address appears in parentheses
 *         following full name; email address may be abbreviated to a local
 *         address if the full address can be expected to be known.  E.g.,
 *         Gene Fisher (gfisher@vogon)
 *
 */

[public] class X extends Y implements Z {

    /**
     * Prose description of the method, describing what the method does,
     * not how it is implemented.  Describe the use of each parameter by name,
     * refer to the instance object as "this", and use the word "return" to
     * describe the return value if there is one.  Also describe each data
     * field used as an input and each data field modified as an output.
     * Modification to a parameter or data field includes indirect
     * modification to the value of a reference parameter or data field.
     * Stylistically, use complete sentences, avoid passive voice.
     *
     * @param   -- brief description of each parameter, one line per param
     * @returns -- brief description of return value, if non-void
     */
    public T1 methodName(T2 t2, ..., Tn tn) [throws ...] {

        /*
         * Include comments for each local variable and comments above each
         * line or group of lines that describe how the method works.  All
         * but the "totally obvious" lines of code should be commented.
         * Comments for variables should be descriptive noun phrases.  Comments
         * for code lines should be in complete sentences.
         *
         * All code comments should be formatted exactly as as this one is: (1)
         * start with "/*" on a separate line, indented to the current level of
         * code indentation; (2) start each comment line with "*", indented to
         * current indentation + 1; (3) end with "*/" on a separate line,
         * indented to current indentation + 1.
         *
         * See below under "indentation and spacing conventions" for further
         * discussion of the format of code within a method body.
         */

    }

     ... other public methods ...

    Note no public or private data fields 


    Protected methods in same format as public methods. 

    /** Comment describing data field */
    protected T1 varname;

     ... other protected and private data fields ...
};


  4. Indentation and spacing conventions.

    1. Except for the specific indentation shown within a class definition above, indentation is every 4 spaces.

    2. Do not use tab characters for indentation or spacing, since tabs are interpreted differently by different program editing and viewing tools.

    3. The following is a template for indentation and spacing of Java method bodies; blank lines are significant. 
      T1 methodName(T2 t2, ..., Tn tn) {

    /* Comment ... */
    Tv1 tv1;
    ...

    /** Comment ... */
    Tvm tvm;

    /*
     * Comment ... .
     */
    for (...) {

        /*
         * Comment ... .
         */
        if (...) {
            ...
        }
        /*
         * Comment, if necessary.
         */
        else if {
            ...
        }
        ...
        /*
         * Comment, if necessary.
         */
        else {
            ...
        }
    }

    /*
     * Comment ... .
     */
    while (...) {
        ...
    }

    /*
     * Comment ... .
     */
    for (start-expression; while-expression; end-expression) {
        ...
    }

    /*
     * Comment ... .
     */
    for (long-start-expression ... ;
            long-while-expression ... ;
                long-end-expression) {
        ...
    }


    /*
     * Comment ... .
     */
    switch (...) {
        /*
         * Comment, if necessary.
         */
        case c1:
            ...
            break;
        ...
        /*
         * Comment, if necessary.
         */
        case ck:
            ...
            break;
    }
}
      In the preceding commenting convention, the '//' style of comments can be used instead of the '/* ... */', but the two styles should not be mixed. For multi-line comments with '//', format as follows: 
      //
// Comment ...
//

    4. Note that except for the indentation of cases in the switch statement, preceding conventions are consistent with the Sun conventions.


  5. Follow all of the naming and capitalization conventions defined at the Sun site.

  6. Size limits.

    1. No method may be longer than 50 lines, except as noted below. The 50-line length does not include comments and blank lines. This rule may not be achieved by condensing lines in such a way as to violate any of the preceding formatting conventions. E.g., the following is legal 
      for (i=1; i<=n; i++) {
    if (i % 2) {
        x.Foo1(i);
        x.Foo2(i);
    }
}
      the following is NOT legal 
      for (i=1; i<=n; i++) { if (i % 2) { x.Foo1(i); x.Foo2(i); } }
      nor is even the following 
      for (i=1; i<=n; i++) {
    if (i % 2) {
        x.Foo1(i);
        x.Foo2(i);}
}
      The following are exceptions to the 50-line rule:

      1. Graphical user interface code builder.

      2. Other segments of code for which the author can rigorously justify the reason to exceed the 50-line rule, where "rigorously justify" does not mean "I'm too lazy to break it up into method calls".


    2. No class may have more than 25 public methods plus 25 protected/private methods, i.e., no more than 50 methods total. If a class has fewer that 25 public methods, it may have up to 50 methods total, however it may never have more than 25 public methods. Typically classes should have far fewer than 50 methods total.

    3. No class may have more than 50 data fields.

    4. Note that combining the 50-line rule with the 50-method rule means that no .java file can be longer the 2500 lines of code, excluding comments. Typically, .java files should have far fewer than 2500 lines.


    Scoring

    Scoring of 102 programs will be based on execution results and adherence to coding conventions. Points for program execution are defined in the test drivers for each program, on a 100-point scale.

    After the execution score is determined for a program, points are deducted for any violations of the conventions specified in this handout. The following are the specific deductions:



    The total maximum deduction for convention violations is 30 points out of 100. If deductions from the specific categories above add up to more than 35 points, the total deduction will be limited to 30 points overall.


    index | info | lectures | labs | programs | solutions | examples