The following style rules are intended to be language-neutral and to express features common to all well-written programs in modern mid-level to high-level languages. I have tried not to include rules on which many reasonable people disagree. Low-level languages (e.g. assembler) and older or strange languages (e.g. FORTRAN) have different conventions, but much of the following still applies.
These guidelines describe an ideal to strive for. In practice, no one follows all these guidelines perfectly.
Be neat.
Be consistent.
Follow the conventions of the programming language you are using.
It is not sufficient for your program to produce correct output. It must also be easy for someone else to read and modify. That is, it must have clear code structure, good commenting, and good formatting.
When writing English, whether extended portions or fragments (e.g. comments), use correct spelling and grammar.
Humor must not get in the way of readability.
No lines longer than 80 characters. Many reasonable displays (e.g. laptops) still can't nicely display text wider than 80 characters.
When the following are too long to fit on one line, later lines should be indented relative to the first line:
There are major two styles for indenting:
In addition to these rules, try to imitate the specific conventions for your language. If emacs has a mode for your language, hitting TAB will usually indent the correct amount.
A whole-line comment should be indented the same amount as the following line of code.
A comment at the end of a line of code should be separated from the code by a couple of spaces. If there are several such comments on nearby lines of code, line them up.
Leave 1-2 blank lines before each function (i.e. before the comment right above the function). Also use blank lines to separate other significant blocks of code or comments. If you use a lot of blank lines within each function (e.g. to separate significant parts of the function), leave more blank space between functions.
Follow directions given.
In particular, be sure you have named files correctly and submitted all required files.
If submitting by email, clearly distinguish between MIME attachments and including the code directly into the body of your message. The distinction often matters to the person receiving your email.
Do not submit in parochial formats (e.g. Word format, latex) unless you have good reason to believe the recipient can decode them.
Margins should be at least 1 inch on all sides. The lefthand margin should be at least 1.5 inches if you bind along the lefthand side.
The font should be at least 10-point and not some wierd ornamental font (e.g. Blackletter).
The paper should be white or lightly tinted.
Text should be dark, preferably black or blue. Avoid red except where there's a real need (e.g. in multi-color figures), because most instructors and proofreaders correct in red.
The pages should be stapled or bound in some other neat way (e.g. velo bound). Don't fold and twist one corner of the pages: it makes your homework stick to other documents. Most faculty will be happy to let you use their stapler briefly.
Your name should be on every page, particularly if you were unable to find a stapler.
Anything handwritten or hand-drawn must be legible: write neatly and darkly.
Variable and function names should be informative. Very short (e.g. 1-2 character) names are unacceptable. Exceptions:
Variable and function names should follow the standard conventions for your programming language. Conventions include whether names are long or short, how to use punctuation (-, _, !), and when to use upper vs. lower case letters. For example, the function to set the first element would be setFirstElement in Java, set_first_element in C, and set-first-element! in Scheme.
Don't hardcode magic numbers into your code. Instead, set up symbolic constants with meaningful names.
Each function should be short enough that you can see the whole thing at once in your editor window.
Exceptions:
Except in very low-level languages (e.g. assembler), avoid global variables and goto (jump) statements. Non-local jumps (e.g. C longjmp) should be used very rarely and only when there is no other reasonable approach.
Exception
When writing a case/switch statement, it is usually bad to let one case "fall through" to the next. In the rare cases where this allows more straightforward code, explicitly comment the fall-through. Do not create similar fall-through behavior by putting code in the tests of a Lisp COND statement.
Within the conventions of your programming language, you still have a range of choices. Making these consistently will make your code much more readable.
When making modifications or additions to existing code, the new and old code must end up in the same style. Either follow the style of the existing code or update the style of the existing code.
There should be a comment at the top of the file that includes the author's name, the date on which the program was written, the course or project for which it was written, and a short description of what the program does. If this is a multi-file program, it should also state what other files or packages this file depends on and/or what larger program this file is part of.
There should be a comment near the start of each function stating what it does. When necessary, this function may also describe how the function works. The most common style is to put this comment immediately before the function. However, some reasonable people put it right below the line(s) declaring the function and its input/output types.
Exceptions:
When a function does something unexpected or has unexpected requirements, explicitly describe them in a comment. Consider rewriting your function to give it more standard behavior. If there is a good reason for the odd specs, include the reason in your comment. For example:
Remember to add comments when the reader should notice that something is missing, e.g.
Comments should not recap what the reader can easily see for himself, e.g. the following are bad style
// loop from 0 to n-1
for (i=0; i < n; i++){
x = x + 2; // increment x by 2
}
public static int foo (...){
....
} // end of method foo
Exception:
Comments should use both upper and lower case, following standard English conventions. Use all caps only for occasional words that need to be emphasized.
If a comment is long enough to look like most of a sentence, it should be written as a full sentence, starting with a capital letter and ending with a period. Exception: this rule is often ignored when the sentence is short.
Large programs should include documentation explaining how the program as a whole works, what data structures it uses, what the names of its code file are, how to compile and run the program, etc. This documentation should usually be in a separate text file (often named README).
Some assignments specify exactly how the program should compile and run. When this is not the case:
Documentation should list any known bugs or limitations with the code and describe any extra features.
Documentation should be written in English. Include fragments of code only rarely, when required to make a specific point clearly.
Do not over-use itemization. Most of your documentation should be written in paragraphs, like a humanities paper. It is almost never ok to nest itemizations.
A paragraph should normally contain between 3 and 8 sentences, and be no more than about 20 lines long.
Leave one blank line before each paragraph, before each item in an itemization if the items are long, and before and after an itemization.
Long documents should be divided into sections, with meaningful headers. Format section headers in some distinctive way. Put blank lines before and after them.
Documentation should be a story about the code, as it exists when you have finished. It should not be a story about you and how you built your code. Comments about yourself and the process of code construction should be made rarely and only when there is a specific need. (E.g. "This assignment was too hard and took 40 hours to complete.") Organize your documentation according to the logical structure of your code, not in chronological order of construction.
If you are upset with the course or assignment, don't vent in the middle of your code, use rude variable names, or the like. We do want to hear your comments. Just put them somewhere sensible, e.g. at the end of your documentation or at the top of your program. Also edit out rude words: they cause many people to listen less carefully to your comments. It often helps to let off steam by writing a really nasty, rude set of comments, then wait overnight to get perspective, and then write the comments you actually intend to submit.
This page is maintained by Margaret Fleck.