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 we may create during testing. 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.
• Brief comments before the definition of each major procedure or group of procedures detailing:
  • What does it do?
  • The use of each parameter.
  • Preconditions that must be met when the procedure is called.
  • Output, return values and side effects (if any).
• Similar explanation is expected for each non-obvious variable, structure, or class declaration.
• Brief comments at any point in the program at which the reader needs help in understanding. Comments which merely rephrase code are unnecessary, distracting, and a potential maintenance hazard (often code is changed, but the comments are not). Comments should edify the code, not repeat it. Use of good variable names and function names can help keep code self-commenting.

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 using methods for structuring programs taught in the course.