ENCE 3240: Computing Systems Hardware Design
Commenting Style Guidelines for Laboratory Assignments
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:
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:
// 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)
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.
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.