Standards for Presentation of Classwork

Overview: This document lays out the standards that will be used to evaluate the form and content of submitted homeworks and programming assignments. These standards apply to all work submitted for evaluation, including quizzes, exams, assigned homeworks, and programming assignments.

Let me begin by saying that these submission standards are not designed to make your life harder, or to impose some sort of police-state, hard-nose controls on your "natural creativity". Rather, the point is to teach you to present your hard work as...well...as a presentation. That is, in such a way that a reader/evaluator is effortlessly guided through a sequence of clearly organized materials in such a way that he or she can not fail to appreciate your true brilliance.

Unless specifically requested, I do not accept emailed submissions! You are responsible for printing, collating, and packaging up your own work. No exceptions!

Overall Presentation:

• Legibility. If we can not decipher ANY part of your work (e.g., name, student number, something in the content), then there is no way it can be evaluated.
  1. Truncated lines. A perennial problem in this respect is long lines in source code that are truncated because they run off the edge of the page. This is unacceptable. Use a print utility like "a2ps" to format the print job and wrap long lines.
  2. Wrapped lines. The fact is that even wrapped lines make programs hard to read (can't see the indenting!). Thus, an excessive number of wrapped lines is unacceptable as well. So what's "excessive"? Essentially, any line wrapping in comments is under your control (you can freely end lines where you want to) and thus is unecessary. Of course, occassionally, you will need to write a long continous line of code which will wrap on the printout. This is okay, just try to avoid it where possible.
• Cover Sheet. A cover sheet is mandatory for all assignments. Your name, the class, the assignment title/number and student number should appear prominently. If the work is not machine-printed (e.g. computer output), you should block letter your name (see legibility, above).
• Stapling. This is easy: STAPLING IS THE ONLY ACCEPTABLE WAY TO SUBMIT MULTI-PAGE WORK. No dog-ears, no paper clips, no rubber bands. Work that is not stapled is simply unacceptable. If you do not have a stapler or have forgotten one, you can always ask to use one in the Engineering front office. Note that this strict policy not only makes life easier for me, but also protects you against the inevitable lost pages associated with other techniques.

Submitting Problem sets:

Occassionally, I will assign problem sets from the end of a book chapter, or handed out in class. Once again, the key to formatting this work is legibility. To wit:

• Each problem must be clearly identified. Usually this just means putting the problem number.
• Problem statement. Begin each problem exposition with a brief restatement of the problem. So, for example, you might write "Problem 4.13: Modify the iterative bubble-sort algorithm given in the text to be recursive." Nothing major; just a quick summary of the problem.
• Show your work! This is the only way partial credit can be assessed for incorrect answers!

Submitting Source Code:

Most programming problems will require you to submit (either electronically or in hard copy) your source code for evaluation. Your overall goal here is two-fold: First and most important, you want to make it easy for a reader to discern the algorithm implemented by your code. This process of understanding must occur at multiple levels: the reader should be able to immediately grasp your overall approach to the problem (e.g. how you broke it up or modeled it in general); from this should flow an understanding of how the various subcomponents interact to produce the desired functionality; and finally, it should be clear how various subcomponents satisfy their purpose. Second, it should be easy to see how/where the code in the source file generates the output (see next section) presented for the program; ultimately a grader will want to be convinced that the source code presented really does produce the output you've submitted.

What does this all mean? One thing: plenty of clear, concise comments. Here are some guidelines to help you put this maxim into practice:

• Begin the program with a broad description of how your code tackles the assigned problem. For instance, you might briefly introduce all the major classes, and sketch out how they interact. This is invaluable for priming the reader (who, after all, is trying to evaluate the work) for what is to come. No need to give page upon page of detailed thought processes concerning program design. Just sketch out what you did.
• Every CLASS file should begin with a paragraph describing the class, what it does, who uses it, and mentioning any significant design details.
• Every method definition within a class should begin with a descriptive comment outlining the method, where/who calls it, and overall comments on the algorithm the method implements. It should also give a brief description of method parameters, and who calls the method.
• In-line comments should be included to guide the reader through the code within any but the most trivial methods. Be sensible here; don't put in inane comments like
  "foo= 2+myValue; // assigning two plus myValue to foo".
  This sort of comment is useless clutter. What is useful is more general comments describing what chunks of code do, e.g.,
  "// The next few lines find and delete extra blanks in the input string".

Note that these commenting guidelines apply to BOTH printed and electronically submitted source files. And it is worth emphasizing again that the whole point of these comments is to make it easy for a reader/grader to instantly grasp how your code works. This will ensure that you get maximum credit and -- in cases where the code does NOT quite work -- will help you get as much partial credit as possible.

Submitting Program Output:

For most people, the program output is the LAST thing they think about. Usually, they print off a snapshot of the output on their way to class, and just attach it to the back of their packet. This is ironic because, in evaluating the work, the FIRST thing the grader looks at is the output. Thus, you should spend a few minutes making sure your output is readable and easy to understand -- grab a pen and a highlighter and add a few annotations to what the printer just spit out. Some guidelines:

• Where is it? It is VERY frustrating when you can't find the program output in the mess of source code.
  1. Output should always be on a separate page(s) from the source code.
  2. On multi-part assignments, output for a given part should be paired with the source code for that part. You may choose to present the output before the associated souce, i.e. output for Part A appears directly before Part A source, which is followed by output for Part B, then source for Part B, and so on.
  3. Output should be clearly identified as the output (e.g. By writing the heading "Program Output" at the top of it in bright felt tip).
• What is it? Programs may produce lots of output, perhaps corresponding to the different parts of a programming assignment. You should annotate the output to make it clear what part of it corresponds to what parts of the program. Use a highlighter to distinguish commands typed by the user from output generated by the code. For instance, you might highlight the command "> myObject.run(listObj1)"; in the margin next to it you might write "Test the module for Part one by passing it the List Object created earlier".

Summary

Again, the point of all this is to make it immediately obvious to the reader/grader what's going on. Those of you who have graded assignments for other courses know how frustrating and difficult things get when all you have is a rat's nest of partially unreadable, poorly commented papers. Make things easy on the grader, and (s)he will find it easy to give you maximum credit.