CS 410 -- Software Systems -- Spring 01

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?
• Documentation and structuring.

Here are some details of the last point.

External documentation.

You can lose all credit if your code is not understandable from the written documentation. Good documentation will also convince the grader that you grasp the meaning of your solution (as opposed to having hacked it into working). The explanations should be direct and concise, not flowery or repetitive. You must describe the following.

• What problem does the program solve?
• What kind of input and output is expected?
• What method did you use in the solution (in case this is not obvious)? What are the main parts and what is the purpose of each part?
• What other conditions are needed for running the program (if any)? What other effects will the program have (if any)?
• How to compile and run the program (if it is not obvious)?
• What error messages does the program produce, in what cases?
• If the solution given by the program is incomplete, what portion of the problem does it solve, e.g. what restrictions are needed on the input?

Internal documentation

• A program header containing the name of the author, login name, assignment number and date.
• 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.
  • 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 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 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 or Perl mode) helps doing this and helps also to discover many syntactic errors early (though the Perl mode is not perfect).

Naming conventions

• Names of variables, constants and functions must clearly indicate the function and type of the named object. A good idea is e.g. in C to end the name of all pointer variables with a "_p" and the names of all types with a "_t".
• 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 (I prefer underscore).
• Variables and functions belonging to a functionally related group should have a common prefix in their names. E.g. the names of all string manipulation C library functions begin with "str".
• The names must be self-explanatory not only for you but also for others reading your code. It is, however, OK to use a one-character local variable within a small (half-page) procedure.

Global variables

Try to avoid global variables, other than constants. Here are some ways to decrease their number.

• Use an extra parameter in the function call.
• If necessary, let this parameter be "call by reference", (pointer to a variable in C) so that the function can change the value of the variable it points to.
• Use static local variables in C or modules in Perl.
• Use static global variables in C.
• Group related variables into a structure.