CMPS 111: Introduction to Operating Systems
Coding Style
Operating Systems are extremely complex software systems. By their very nature
they are confusing and difficult to understand. Poor coding style only makes the
situation worse. Therefore, I expect exemplary coding practices from everyone
in this class. If you fail to follow these guidelines, you will lose significant
points on your assignments even if they are otherwise perfect. As the quarter
progresses I may add to this as necessary.
Coding Style
Good coding style enhances program readability, clarity, meaning,
simplicity, etc. Good coding style is an art as well as a science,
but there are a few simple rules you can (and in this class, must)
follow that will greatly enhance the readability and clarity of your
code.
Comments:
- Every file must contain a comment at the top that describes the code in
that file. In any file that you create, this comment must start with the word
"CREATED: " followed by your name and the date that you created
the file. In any file that you changed, include the word "CHANGED: "
followed by your name and the date that you changed the file.
- Every function must have a comment before it describing what it does, what
parameters it takes, what it returns, and what assumptions it makes.
- Every non-trivial block of code must have a comment saying what it does.
For our purposes, non-trivial means 3-10 lines of code, depending upon the
complexity. As a guideline, you should have about as many lines of comments
as you have lines of code.
- Every comment must be indented properly given its location in the file,
on the preceding line and aligned with the code it describes.
- Finally, in any existing file that you change, place a comment at the beginning
of each change indicating where your changes are. The comment should include
"CHANGED: " and your name and the date, and a brief description
of the changes.
Indentation:
- After every left brace, indent a fixed number of spaces (2-4).
- With every right brace, unindent the same amount.
- Everything else should be aligned accordingly.
- Long lines (printfs, comments, etc.) that wrap around should be broken
into parts so that they do not wrap.
- Do not indent with tabs unless you know that your editor substitutes spaces
for tabs (emacs does).
Spacing:
- Every comment (except the one at the top of the file) must be preceded by
a blank line. There should be no blank line between a comment and the code
it describes.
- A blank line (and often a comment) should come before every chunk of code
that does something different from the code before it.
- A blank line should come between all declarations and all other
code in a function.
- A blank line should follow any right brace, unless the following line
also has a right brace.
Braces:
- When declaring a function, the braces go in column 0. The left brace goes
on the line after the function declaration, and the right brace goes after
the body of the function.
- Any other time, such as with an if, for, or while, the left brace goes
on the same line as the if, for, or while, and the right brace aligns with
the if, for, or while on its own line.
Identifiers:
- Identifiers (functions, variable names) should use only
lower-case letters, with underscores between words.
- Identifiers should be as meaningful as possible, without growing too long.
Don't use more than two words in your identifiers unless absolutely necessary.
- Single-letter identifiers may not be used except as loop counters, and
then only when something more meaningful is undesirable for some very good
reason.
And, of course, you may not use global variables unless no other solution will
work. Any global variables must be justified and explained in your design document.
Links to Other C Style
Guides - the first one is especially good.
