CS/CE 218 Style and Documentation Guide

Up to 25% of your programming grades are based on style and
documentation.  This file contains information on how to document
files and functions, and how to format code so it is easy to read.
Also, some coding issues are discussed.


Documentation of Files

Each file you produce should begin with a comment containing
   1. the file name,
   2. the assignment (and question number)
   3. author,
   4. TA,
For a file that contains more than one function, you might also want
to include a comment describing:
   5. the purpose of the file
For example, if the file contains a main program you could describe
how to call that program, its options, etc.


Documentation of Functions

Each function should include comments detailing the relationship
between its arguments and result, including any side effects on
globals or files.  Prof. Leavens recommends the style illustrated by
the following examples:

	double sqrt(double x)
	   /* requires: x >= 0.0 */
	   /* ensures: result*result == x (approximately) */
	{
	   ...
	}

	void swap(int *x, int *y)
	   /* modifies: *x, *y */
	   /* effect: swap the values in *x and *y */
	{ ... }


	double random()
	   /* modifies: seed */
	   /* ensures: result >= 0.0 */ 
	{
	   extern double seed;
	   ...
	}
	
	void error(const char *name, const char *msg)
	     /* modifies: stderr */
	     /* effect: print name, a colon, a space, msg, and a newline
	                on standard error output, then exit(1)
	      */
	{
	  fprintf(stderr, "%s: %s\n", name, msg);
	  exit(1);
	}

It's not necessary to be an expert at this style to use it effectively.
None of this is formal, it's just stylized English.  The idea is to be
precise, but to also communicate to the reader what you want to say.

The idea is to describe the result of the function (if any) in a
comment of the form /* ensures: ... */ or /* effect: ... */.  Effect
is used to describe functions with side effects; ensures is used to
describe the relationship between the result and the arguments in a
pure function.  When in doubt, just use "effect:" and write English
after it.

The /* modifies: ... */ clause lists all globals and externals that
are changed, as well as anything changed through a pointer.

The /* requires: ... */ clause states assumptions you're making when
implementing the function. These should be taken into account by the
caller of the function.  For example, in sqrt, the caller is required
to pass in a value zero or greater.

(For those of you who know (say from 411),
"effect" and "ensures" label post-conditions, and "requires" labels
a pre-condition. The "modifies" clause gives a frame axiom.)


Indentation

Code must be indented so as to show its structure.  You may use any
style so long as you are consistent.  Emacs will help you indent code
similar to Kernighan and Ritchie's text.  The Emacs manual includes
information about this.  See also the Unix on-line manual entry for
the program ``cb.''


Coding Issues

This section covers some things to think about when writing code and
defining functions.  These are suggestions, not rules.  When in doubt,
ask your TA.

Each function should have a clearly defined purpose.  If your function
does two main things, consider using two functions.  Or if your
function is "too long," consider decomposing it into several
sub-functions and using a function to call those.

Do not repeat significant pieces of code.  If more than a few lines
are duplicated, write a function.

Input to functions should be passed as parameters, not in global
variables.  (The global variable space should remain uncluttered.
This makes the program easier to understand.)

The code you write should be clear.  If there is a faster or more
efficient way to code something, do not necessarily do it.  This means
you can break up long expressions into seperate statements, store
intermediate results in variables with meaningful names, etc.