A goal of CS100 is for you to learn to write programs that are not only correct but also understandable. These guidelines should help you toward that goal. We ask that you follow these guidelines when writing programs in this course. They will give you a good basis for developing a style of your own as you become a more experienced programmer.

This page will be gradually fleshed out as we learn more and more programming constructs. If you wish to read ahead and will not be bothered by reading about constructs we have not seen yet, then go ahead and skim the Java style guidlines, which contains general principles and thus are applicable to Matlab and other languages.

Indentation

The indentation style is follows a simple, key principle:

Principle: Indent Substructures.

This explains indentation for conditionals and loops, and explains why comments for a group of statements should go above, with the corresponding statements indented below the comment: the corresponding statements are substructures implementing/fleshing out that statement-comment.

This principle is especially important because good programming involves breaking larger problems into smaller problems. The way the sub-problems fit/nest into the larger problems should be immediately apparent from the code for maximum clarity. The principle above provides that clarity with a simple, unifying principle consistent with our other conventions for indentation.

However, you should be aware that not everyone uses this convention. Sometimes it is not relevant, and sometimes there are rules/forces against it. For example, CS312 tends to use a rather different program language to write rather different programs, in which other styles might be appropriate. (Another example is that J and M instructors often use a variety of editors with different methods for formatting.)

You should apply the principle in your own code for CS100, but if you would rather not, keep in mind that your project scores will not suffer unless you make a handful of other errors -- you can get a perfect score if you make only a few errors.

A Peek into the future: Functions

(You probably don't need to worry about this until the 2nd week or later.)

Since we tend to think of functions as black boxes, their behaviour should be clear to a user:

Clearly specify inputs and outputs using "Pre-conditions" and "Post-conditions".

Pre-conditions specify:

• the meaning of each of the input parameters
• what kinds of data the input parameters are allowed to contain
• constraints regarding when the function can be called, e.g. "X is positive".

Post-conditions specify:

• what values are gauranteed to be in the output parameters
• the format (what kinds of data) of the output parameters
• constraints that are guaranteed to be true of the output parameters, e.g. "Y is between input parameters A and B, inclusive"
• any side-effects that the function might have, e.g. input/output interaction with the user, plotting data etc.

What this means in terms of Matlab commenting:

1. Write a "summary" comment line with the names of the function and input and output parameters and a brief description of what the function does.
2. In the comment lines that follow, specify the meaning of the input parameters, taking care to mention if they need to be strings, doubles, matrices etc.
3. Finally, clearly specify what values the function puts into output arguments and any other I/O, plotting related work that the function does.