CS 203 Java Software Evaluation

For CS 203, evaluation of software is based primarily on its correctness, completeness, and appearance.  Correctness is assessed based on the algorithm used and the ability to obtain correct output.  Completeness is assessed based on the coverage of the tests cases and the program’s results on these test cases.  Appearance is evaluated on the basis of the points listed below.

 

  1. Opening Comments:
    1. Your name, course number, section number, lab section number, and a rough date (you can use the due date) should be given in a comment at the top of the file containing the main function.  When major changes are made to the program, add one or more lines describing the change and giving the new date.
    2. Your name and the rough date should be given at the top of every .java file
    3. The overall purpose of the program should be specified in a few sentences before the main function.  This description may be the similar to the problem statement given in the external documentation.
  2. White space
    1. Blanks, tabs, and new lines should be used to ensure that the overall appearance of the program is neat.
    2. Align lines on the left, except where indented (see topic 5, “Indenting” below) or continued from a previous line.
    3. Align variable names in declarations (** see note at the end).
    4. Place blanks on both sides of every operator, such as =, +, -, *,  /, <. <=, >, and >=.
    5. Restrict the length of lines to 80 characters.  If a statement is longer, you may start a new line anywhere a blank is allowed (except within quoted strings).  If a quoted string is too long to fit, in most cases it can be broken into several quoted strings, e.g., instead of printing one long string, print two shorter ones instead.
  3. Constants
    1. Use symbolic constants, such as MAX_RATING, instead of specific numbers in your program.  (However, 0 and 1 may be used freely in your programs instead of symbolic constants.)  These symbolic constants make clear the relationship between numbers, e.g., MAX_RATING and MAX_RATING – 1 are used instead of 100 and 99 to document the relationship between the two constants.

final int MAX_RATING = 100;

    1. The names of constants should be given in all uppercase letters with underscores between words, e.g., MAX_RATING (**). 
  1. Declarations
    1. Declare all variables at the beginning of the main program or a function.  As an exception to this rule, you may declare the loop counter variable directly in the for statement.
    2. Variable names should not be given names in all uppercase letters.
    3. As long as variable names describe the purpose of the variable well, no comments are needed beside the declarations. Trivial variables, such as loop counters, do not require comments.
    4. Choose a name for a variable that reflects its purpose. 
    5. In general, begin a variable name with a lowercase letter (**).
    6. For variable names consisting of several words, each succeeding word should begin with an uppercase letter (following the convention of the textbook and the online notes), e.g., myName, fullAccumulatedTotal (**).

 

  1. Indenting
    1. Use indenting to demonstrate the structure of your program.
    2. Indent the contents of every function and anything between braces, i.e., { and }.
    3. Place braces, i.e., { and }, on separate lines, aligned with one another (**) and the preceding line (main/for/while/if).
    4. You may use your own judgement to choose the amount to indent for each level of indenting.  Choose one amount between 2 and 8 spaces and use it consistently.  The online notes use two spaces or one tab, several programming environments use four spaces by default, and using the tab key in a natural fashion on hercules gives 8 spaces.
  2. Comments within the Program
    1. Comments should add information to the program for the benefit of the reader.
    2. You may either add comments on the right side, as is done in the textbook, OR place comments on the line immediately before the line to be commented (and aligned with that line (**)).

// Read and examine all input ß This comment is before a group of lines

while (input != DONE)

{

            input = readInput( );  // ß textbook puts comment here

            if (input != DONE)

            {

                        examineInput(input);

            }

}

    1. A comment that describes the overall purpose of a selection or looping statement is more valuable than one that simply “echoes” the code; e.g., avoid comments such as:

x = x + y;   // add y to x.

    1. You do not need comments for functions containing three or fewer lines of code, if the purpose of the function is obvious from its name; e.g., setXPosition(int x);
  1. Classes
    1. Each public class should be declared in its own .java file.  This file should have the same name as the class.
    2. Class names should be in lowercase letters except each word, including the first one, should begin with an uppercase letter.  For example, e.g., MyClass, AReallyLongClassName (**).
    3. A high level comment explaining the purpose of a class should be given directly before it.
  2. Subprograms (functions other than main)
    1. If a class contains a main function, it should be the first function in the class.
    2. The constructors for a class, if any, should follow the main function.  If a class does not have a main function, the constructors, if any, should be the first functions in the class.
    3. Function names should be in lowercase letters with each word except the first beginning with an uppercase letter.  For example, e.g., myGoodFunction (**).
    4. For each function, a comment explaining its purpose, parameters, and result should be given directly before it.

 

** - indicates that you may choose another style for these items, but your style must be neat and must be followed consistently.  Be prepared to show in writing rules you use for formatting.