Introduction

    This handout describes a set of recommended laboratory write-up/report conventions. Note that these are only recommendations, and I do not claim that these conventions are the best. You are free to use your own conventions as long as they are clear and follow the same goals that this guideline describes.

    As far as the grading of laboratory assignments is concerned, comments are needed in order to receive partial credit for your work.NO partial credit will be given if the labs you write for laboratory assignments are not commented! Some people will go too far and comment each line of source code (if applicable) and diagram. This is not necessary. In fact, this practice should be avoided whenever possible since they tend to make the code and our layout diagram harder to read. Instead, you should try to write comments that explain the logic (instead of the mechanics) of a particular block of code and/or diagram.

    For the most part, the concerns addressed here do not directly affect the correctness of the labs you will write, that is, how effectively your labs communicate the desired behavior to the computer. Instead these conventions are intended to make your labs easily read and understood by people. A clearly documented lab write-up facilitates:

• writing correct SRC commands and confidence in that correctness
• debugging (both by yourself, as I as someone else helping you debug, e.g., a TA)
• use of your working lab write-up by others
• reuse for the same or a related purpose at some later time
• lab write-up modification and maintenance
• grading

File Description

    At the top of each lab write-up will be comments whose purpose is to assist us in identifying the lab write-ups as I grade them. It is very important that you edit these comments to include the appropriate user-specific information. This is also a good place to put a brief description of the contents of the lab write-up. An example of this follows:

// FILENAME: .SRC
// AUTHOR: Patrick Lynn
// LOGIN: lynn
// STUDENT ID: 123-45-6789
// ASSIGNMENT: lab2
// RECITATION: 1

The recitation number is the start time of the recitation you are attending. (if applicable)

Lab Comments

    When commenting your labs, you should try to think from two points of view: as someone who may have to use the lab write-up, and as someone who may have to maintain or modify the lab write-up. Remember that you (hopefully) already know how your lab write-up works and why it is structured the way it is. Put yourself in the position of someone else reading the lab write-up for the first time when writing comments.

Naming Conventions

    Choose informative and easily understood identifiers (names for variables, functions, constants, classes, and so on). Be wary of abbreviations --- even if they appear to be clear to you, they might not be to someone else (or even to you) in six months.

Readability

• Indent the body of flow-of-control statements, The particular style (how many spaces you indent, where you put the delimiting brackets) is not so important,
• Choose a style and adhere to it consistently.
• Separate elements of expressions with spaces. This makes it much easier to read. Don't be afraid to continue an expression on the following line.
• Blocks of code that accomplish subtasks should be separated by a single blank line.