Dr. Lisa N. Michaud
Fall 2013 Courses
STYLE RULES FOR DR. MICHAUD'S COURSES
The key to writing good computer programs comes in several pieces. Obviously, the correctness and execution of the program itself is an important part. However, a part which is equally important is the design and its documentation. We never write programs in a void; we are always part of a larger community, whether that community involves fellow students, professors in a programming course, or co-workers in a future job. Almost always, there will be someone who is going to have to read or make use of this program after you have completed it, and that someone is going to have to be brought up to speed on what you were trying to do, how you were doing it, and how your contribution should be used. That someone could be you; you would be surprised how hard it is to remember how a program was written only a few weeks after you put it aside!
Most (if not all) modern computer programming languages include some way to provide documentation alongside your program itself. This documentation is ignored by the computer, but any human reading your program will be thankful for it.
An excellent rule of thumb is:
In other words, the comments should be the first thing you put into a new file. Use them to lay out your approach in pseudo-code; you can then fill in the details with the actual program. A bonus to this approach is that you do not have to worry about adding comments 5 minutes before your assignment is due.
When you provide documentation for any program, you should keep the following factors in mind:
The primary vehicle for documenting a program is the comment, an aside within the program itself that is "invisible" to the computer. In this course, you must always provide the following comments at a minimum:Header Comment: This comment occurs at the top of every source code file and every header file. Its minimum content is:
Function/Method Comment: At the beginning of each function or method you define, you must have a comment explaining the function with a minimum of the following:
Internal Comments: Inside functions, you must comment both the declarations of variables and any major parts of a function that are not entirely self-explanatory. You do not need to comment every line, but comment sections of a function so that the reader can see what each part does.
As a guiding rule, do not merely repeat in English what the declaration says ("An integer") or what the code says ("Tests to see if it is equal to 42"). Tell the reader what the purpose of that bit of code is.
Closing Braces: Always write a comment on the line of a closing brace. It is never a bad thing to know exactly what control structure is being closed by that brace; when there are many braces, it is useful to know which goes with which.
While languages such as C++ and Java do not require you to indent your code, nor in fact to include any whitespace at all if you wish to smush all of your statements together on one line and never use the spacebar, the return key, or the tab key, it is a necessity for readability that you use all of these three keys in good amounts.
See the example code above for illustrations of all three of these points.VARIABLE AND FUNCTION NAMES
It goes without saying that variable names such as x and y are not very informative unless you are talking about coordinates, and that one-letter variables should not be used for many purposes other than as loop indices. Do not be stingy with the names you give to your variables, functions, and object classes. Do not be cryptic, either. Allow them to be descriptive. Even when you comment their declarations, a reader will best remember that identifier's purpose if the identifier is easy to read.
A very good rule of thumb is:
When defining your classes, keep in mind that abstraction is one of the keys to good design. Therefore, you must:
In C and C++, always place your class definition in a header file with the same name and the implementation of the functions for that class in a source file, also of the same name. In java, where there is only one file for a class definition, the file name must be the same as the class it defines.
A wise programmer once said: "A function should never be larger than one screen." Functions that stretch on for hundreds of lines are not following a modular structure; they must be broken down further into smaller functions. Screen sizes vary, but this general guideline helps give you a heads-up when a function is getting out of control.
The cartoon at the top of this page makes fun of the use of GOTO, but the fact is that control structure abuse is a common and costly problem. Use the following rule of thumb:
The control structure itself must determine the flow of the program. This means that a loop's boolean expression should encompass all possibilities for continuing the loop or stopping. The use of a break, or a goto, should never jump out of a loop, or a branch (if/else). The only place "break" should be used in a C-like language is in switch/case, where it is necessary. It is never considered acceptable to use "goto," unless you do want to be eaten by a velociraptor.