CS113 Programming Homework Format Guidelines

Grading criteria

• Does it work? Your programs should compile without warnings or errors. They should give the correct answer, both on the example inputs given in the assignment and possibly on arbitrary new examples created during testing, if we test your program independently. You can get at most 30% of the maximum score if the program does not run.
• Is it found correct also after reading the code? (The test set may not have revealed all bugs.)
• The quality of the solution: e.g., is it unduly complex?
• Comments and structuring.

Here are some details of the last point.

Comments

• A program header containing the name of the author, login name, assignment number and date, and a very short description (shorter than the external documentation) of what the program is about.
• Comments before the definition of each major procedure or group of procedures:
  • What does it do? Where will it be used?
  • The use of each parameter.
  • Preconditions that must be met when the procedure is called.
  • Output and possible side effects.
  • What method did you use (in case this needs explanation).
• Similar explanation is expected for each non-obvious variable and structure or class declaration.
• Comments at every point of the program at which the reader needs help in understanding. A comment is unnecessary and distracting if it only rephrases your code in English, without summarizing it or adding any information.

Structuring

• Make the program largely self-explanatory by arranging it in an intelligent way and giving informative names to your variables and procedures. Then fewer comments are needed since you must only comment the non-obvious.
• Maintain consistent indentation. Using Emacs in (C++ mode) helps doing this and helps also to discover many syntactic errors early.

Naming conventions

• Names of variables, constants and functions must clearly indicate the function and type of the named object.
• Follow the convention that constants should be all capital letters, with multiple words separated by underscore "_".
• Within variable and function names, multiple words can be separated by either capitalizing or an underscore (underscore has the advantage that Emacs recognizes it as a word boundary).
• The names must be self-explanatory not only for you but also for others reading your code.

Global variables

Try to avoid global variables: for this, use the methods you learn in the course to structure your program.