Bear in mind that if you choose not to follow these guidelines, you're trusting your grade to the benevolence of the markers and their willingness to sort through any idiosyncrasies.

Code Comments

Uncommented code will receive a grade of zero as comments serve several important purposes:

1. Comments give you the opportunity to demonstrate that you understand the code you are submitting by showing that you can articulate its operation via English prose.
2. Comments provide you a chance to confess where you do not understand something. "Debugging by confession" is a widely used professional technique and a central tenant in extreme programming strategies. Worry less about being penalized for a mistake and more about getting help to resolve the bugs.
3. Comments will assist you in understanding other people's code, a challenge you will likely find yourself facing in this class and elsewhere.
4. Comments help you understand your own code should you be asked to review it weeks (or years) after the over-caffeinated late night during which you cranked it out.

Here's an example of decent commenting from some of George's c++ code:

/** 
    \class GaussianClassifier
    \brief Single Gaussian multidimensional classifier

   Simple multidimensional Gaussian classifier. The classifier
parameters (or model) are stored in the theta control.  When the
mode control is set to "train" the input slice is used to accumulate
information for training.  The final theta calculation is
completed when the control train is set to true.  It can accommodate
non-incremental or batch training. The "labels" control is used to
provide ground truth about the label(s). The output of the classifier is
the ground truth label(s) when the mode control is train.

When the mode control is set to "predict" then the output 
of the classifier is the predicted labels using the trained 
parameter vector theta. 

This MarSystems serves as a prototypical classification/regression 
MarSystem. 
*/

Here's another more humble example from my own (java) code:

/**
 * A more or less simple multimedia player developed with Java Media Framework.
 * Functionality includes loading images from the local file system or on the web
 * via http (or other services if available), looping, limiting play to a user 
 * defined clip and fixing the aspect ratio.  The class could be used in another
 * application, for instance, an alternative UI.  However, a developer would have
 * to be careful to instantiate the static variables fd, wd, and playerPanel.  This
 * is certainly a design problem of this current implementation in
 * need of fixing.
 *
 * This was developed with JMF 2.1.1 port to linux.  A number of codecs appeared to
 * to be missing, such as most, if not all, audio... or partially broken.  MPEG played
 * with very marginal quality.  Quicktime played but without audio.
 *
 * Aaron Hechmer, Multimedia Systems-- CSc 561, 27 January 2004
 */

Here are two more examples from my own code. Yes, they were probably written late at night when I was low on sleep and blood-sugar. So, their main purpose is to help me understand in the morning the horrors of my thought process the night before:

	for (int i=1; i<(coords.length-1);){
	    int when = getTick(i, coords.length);
	    // did Y change?
	    int y1 = coords[i][1] - coords[i-1][1];
	    int y2 = coords[i+1][1] - coords[i][1];

	    // there's a bug here as zero values will default to a "going down" hit... should deal by
	    // perhaps adding a third option or a lookahead that keeps going until it gets a +/- value
	    if (isNegative(i, 1)){
		Color color = (Color)timbre.get(new Integer(i));
		int timbre;

		if (up){  // going up!
		    //System.out.println("Y up when " + when);
		    timbre = 1;

		}
		else {  // going down! 
		    //System.out.println("Y down when " + when);
		    timbre = 2;
		}
		newMessage(NOTEON, 9, noises.getInstrument(color, timbre), when); 
		newMessage(NOTEOFF, 9, noises.getInstrument(color, timbre), when+1);
	    }

	    if (y1*y2 == 0){i+=2;} // so we don't get two zero readings in a row
	    else {i+=1;} // may have incremented by two already
	}	

Similarly, it's very helpful if you include your test cases. Should our test cases fail, we can give you a zero for the problem. Or we might also try running some of your test cases and attempt to find a simple explanation for the failures. Test cases can be provided in a separate file or even in the body of the source code. In the latter format, it's usually best to comment the test cases out (when working in SML or Scheme).

What Else to Hand In

In addition to the README file, be sure to include all your commented source files as well as compiled binaries where appropriate (such as with the c++ assignment).

For some assignments you will be given some skeletal code or source libraries to help your project along. You MUST hand in all of these files as a single functional set. In other words, assume that we don't have any of the background files!

Archives and Compression

If you will be submitting more than one file for an assignment, please place the files in an archive. The archiving utility of choice for this class is tar. Although mostly associated with unix, there are versions of tar that run on MS Windows and, of course, OSX. If you are unfamiliar with the use of tar, please consult its manual pages or look for help online.

Briefly, to archive a set of files with tar, do something like the following:

bash% tar -cvf MyArchiveFile.tar asn1/* README

bash% gzip MyArchiveFile.tar

bash% gunzip MyArchiveFile.tar.gz

bash% tar -xvf MyArchiveFile.tar