Introduction

    This handout describes a set of recommended programming conventions. Note that these are only recommendations, and we 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 machine problems is concerned, comments are needed in order to receive partial credit for your work. NO partial credit will be given if the programs you write for machine problems are not commented! Some people will go too far and comment each line of source code. This is not necessary. In fact, this practice should be avoided whenever possible since they tend to make the code harder to read. Instead, you should try to write comments that explain the logic (instead of the mechanics) of a particular block of code.
For example, do not do the following:

    // i is incremented by 1
    i++;

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

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

File Description

    You will begin each machine problem by executing a setup program that will copy several files to your current directory. Among these files are incomplete versions of the program(s) that you will edit, and eventually turn in by executing the ``make submit'' command.

    At the top of each file will be comments whose purpose is to assist us in identifying the files as we 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 file. An example of this follows:

// FILENAME: List.h
// AUTHOR: Patrick Lynn
// LOGIN: lynn
// STUDENT ID: 123-45-6789
// ASSIGNMENT: mp2
// RECITATION: 9

The recitation number is the start time of the recitation you are attending.

Program Comments

    When commenting your programs, you should try to think from two points of view: as someone who may have to use the program, and as someone who may have to maintain or modify the program. Remember that you (hopefully) already know how your program works and why it is structured the way it is. Put yourself in the position of someone else reading the program 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.

ChanceOfRain = Forecast ( Pressure, WindSpeed, City );

is better than

Rain = Frcst ( Bar, Wnd, Ct );

which is only slightly better than

z = f ( x, y );.
 

Readability

• Indent the body of flow-of-control statements, e.g., if-else, for, while. 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.