CS 110 C++ Software Evaluation

 

Many programs can be designed to solve the same problem.  Even programs that accept the same input and produce the same output may differ widely in their appearance and their algorithms.  For CS 110, 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 should be given in a comment at the top of the program.
    2. The purpose of the program should be specified in a few sentences.  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 MAXRATING, 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., MAXRATING and MAXRATING – 1 are used instead of 100 and 99 to document the relationship between the two constants.

const int MAXRATING = 100;

    1. Declare all constants, either globally (before the main function) or locally (inside the function, with the other variables).
    2. The names of constants should be given in all uppercase letters, e.g., MAXRATING.  Variable names (see Declarations section below) should not be given names in all uppercase letters.
  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. Place a comment describing the purpose of each variable name directly beside it or on a preceding line.  Several similar variables may be described jointly.  Any trivial variables, such as loop counters, do not require comments.
    3. Choose a name for a variable that reflects its purpose. 
    4. In general, begin a variable name with a lowercase letter (**).
    5. For variable names consisting of several words, each succeeding word should begin with an uppercase letter (following the convention of the textbook), e.g., myName, fullAccumulatedTotal (**). Or use all lowercase letters and separate the words with underscores (_).
  2. Indenting
    1. Use indenting to demonstrate the structure of your program.
    2. Place braces, i.e., { and }, on separate lines, aligned with one another (**) and the preceding line (main/for/while/if).
    3. You may use your own judgement to choose the amount to indent for each level of indenting.  Choose one amount between 3 and 8 spaces and use it consistently.  The textbook uses three spaces, several programming environments use four spaces by default, and using the tab key in a natural fashion on replit gives 8 spaces.
  3. 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 given before a group of lines

while (input != DONE)

{

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

            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. Subprograms (functions other than main)
    1. A “prototype” declaration should be given (before the main function) for every function other than main.
    2. A comment explaining its purpose, parameters, and result should be given directly before each function.
    3. No global variables should be used.  (A global variable is one declared outside any function.)  All variables needed by a function should be passed as parameters.  Note:  global constants are allowed, but global variables are not.

 

** - 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.