CS 11 C track: coding style guide

Download the style checker from this file onto your computer. The way to do this is to select the "Save Page As" option in the "File" menu (this works for Firefox; other browsers have similar commands). It will suggest you save the file under the name c_style_check and you should agree. This will put the style checker program into one of your directories (probably your home directory). DO NOT CUT AND PASTE THE CODE INTO A FILE; THAT WILL NOT WORK! Alternatively, you can right-click on the link to the file and select "Save Link As", which is simpler.

Start up a terminal program and use the cd (change directory) command to the directory containing the style checker you just downloaded. Make it into an executable program by typing:

(where $ is the terminal prompt; yours may be different).

Make a subdirectory of your home directory called bin (which just means a location for programs; the name really doesn’t matter but it’s traditional). You can do this by typing

at the prompt (the tilde (~) character is shorthand for your home directory). Note: if you already have a ~/bin directory, obviously you don’t have to do this step.

Move the style checker into the newly-created bin directory:

Now comes the tricky part. You have to adjust your path so that it includes your bin directory. The path is just a list of directories that contain programs; it’s the way the computer knows where to find programs. There is a default path set up for you when you start your computer, but it may not include the bin directory (because most users don’t have one).

To adjust your path you have to do these steps.

First check to see if you already have the bin directory in your path. Type:

at the prompt and if the result includes /home/<your-login-name>/bin then you’re all set and you can skip the rest of the steps in this section.

Otherwise, you need to adjust the path in your terminal initialization file. There are two kinds of "shells" (command interpreter programs) that are used in Unix-style terminals: one is called bash and the other is called zsh. On Windows or Linux, you will probably be running bash, whereas on a Mac you will probably be running zsh. To find out which one you are using, you can type this:

If one of these gives a "not found" error message, you are using the other one. If both give a "not found" error message, you need to talk to a TA. The initialization file for bash is called .bashrc; the one for zsh is called .zshrc. We’ll assume you are using bash in what follows; the changes for zsh are analogous. Check if you have a file called .bashrc in your home directory directory:

If this file doesn’t exist, you might try this:

(or /etc/zshrc for zsh.) If this exists, copy it to your home directory:

If that file isn’t there, you need to see the TAs. Otherwise, continue.

Open up the .bashrc file in a text editor. Go to the end of the file and add this line:

Save the file, get out of the text editor and do this at the prompt:

Now you’re all set. You will be able to use the style checker from any directory you’re in, and you’ll never have to download it again or do any of these steps again.

To style check a file called e.g. foo.c, do:

You can also style check multiple files all at once:

Don’t be alarmed if there are a lot of errors reported; just go through the file and fix them. Some lines will probably have multiple style violations; you should fix all of them. You’ll probably be very annoyed with the style checker at first, but your code will become much more readable as a result. If you think you’ve found a bug in it, let us know at once; this is a (permanent) work in progress. Note that the style checker will sometimes be too stupid to know when it’s in the middle of a comment or a literal string, so it may report errors that aren’t really errors in those cases. If so, just disregard them.

Never, ever, ever use the tab character (ASCII 0x9)! Different people use different tab settings in their editors, and code that looks just fine with a tab width of 2 becomes unreadable with a tab width of 8. Unfortunately, many text editing programs will stick in tab characters without making it obvious that they’re doing it.

Almost all text editors allow you to force tabs to actually print spaces. Some examples:

This is actually Emacs Lisp code, but don’t worry about that. Then exit and restart emacs. Now when you hit the tab key while editing C code, emacs won’t actually put any tab characters in your code, but instead will just put in spaces.

into the editor while in command mode. This will make all tab characters look like ^I (a circumflex accent followed by a capital I). This makes it easy to go through a file and replace all tabs by e.g. four spaces. Better still, you can put this into your ~/.vimrc file:

and when you hit the tab key, spaces will be printed instead.

If you don’t like removing tabs from your code manually, here’s a trick that will help. Let’s say you have a file called foo.c and you’ve run the style checker on it, and every other line has tabs in it. Just do this from the unix prompt ($ in this example):

and your file will no longer have any tabs. On the other hand, this can mess up the indentation, so you should go over it afterwards to make sure it looks presentable and add spaces if necessary. If you don’t, and the result is unreadable, you will probably have to redo it.

The sed in the command line is a program called sed (which means "stream editor"). It does simple editing on files on a line-by-line basis. ^[2] So when you type

it executes a command called s/\t/ /g on each line of the file foo.c, putting the results into a new file called foo.c.notabs. The line s/\t/ /g means "substitute (s) for every tab (\t) character, four space characters (which is what’s between the / / characters), and do it for every tab in the line (g, which means global)". Note that you have to type this in exactly as described or it won’t work.

If you want, you can use more or less than four space characters per tab. Most editors use eight space characters for a tab by default, so that might be a good alternative. That would look like this:

Use a single space to separate variable names from operators, i.e. write

instead of

The only exception to this rule is for array subscripts e.g.

but you can put the spaces in here too if you want. Unfortunately the style checker currently complains if you don’t put the spaces in. Don’t worry about the warning in this case.

Always put a space after a comma. There are no exceptions to this rule.

If you are using a formatting style where the opening curly brace of a block is on the same line as an if, while, or for statement (which we discourage; it’s better to put the curly brace on a separate line), make sure that there is a space between the close paren on the line and the open curly brace, e.g. do

instead of:

because the latter is hard to read. Similarly, leave a space between an else keyword and an opening curly brace if they’re on the same line.

Don’t write lines that are longer than 80 characters long. Long lines tend to be wrapped, or worse, to be truncated when printing out the source. Printing out source code is a valuable way to review your code. It is almost never necessary to have long lines, even for long strings; you can always break up a string like this:

and the two strings will be concatenated together. This will work for any number of consecutive strings. Note that this trick only works for literal strings, not for variables which contain (point to) strings.

For portability, you should restrict yourself to pure ANSI-compliant C code exclusively. Note that gcc will not do this for you. If you want to be safe you need to use several compiler flags:

and make sure that your program doesn’t generate any warnings. (Code which generates warnings will be severely penalized.)

Avoid putting a large number into a file which has no obvious relevance to the surrounding code. This is known as a "magic number" and is often found when setting the size of arrays, e.g.:

The reason for avoiding this is twofold:

The right thing to do is this:

Alternatively, it’s perfectly valid to declare a constant:

Don’t put in code that has no function or no effect. If it’s code that’s was only used for debugging purposes, it should be removed before you submit your assignment.

If a program is called with incorrect arguments, it should detect that and print a usage statement to the terminal. The usage statement should include the program name. The easiest way to do that is to use argv[0] i.e.

Note that the arguments have mnemonic names. Don’t write the usage message multiple times. If necessary, you can define a usage function:

and then call it like this:

Alternatively, you could put a call to the exit() function in the usage() function:

and then call it like this:

In this example, the return 1; line wasn’t needed because when exit(1) is called from the usage() function the program will exit with a return value of 1.

Also, make sure that you use fprintf and print to stderr (the error output stream) instead of using printf, which prints to stdout (the normal output stream).

As a general rule, any error that involves the user supplying invalid command-line arguments should give rise to a usage statement like the ones described above. You should try to make your usage statements comprehensive enough so that one statement will work for all such errors.

For more on the correct format of usage statements, see this page.

Never put more than one statement on a line. It makes for unreadable code. The only exception is in the for line of a for loop, which typically has three statements.

Use parentheses to show operator precedence in all cases except that of multiplication/division over addition/subtraction and assignment statements.

Do not put large numbers of empty lines (> 2) between code sections unless there is a clear need to distinguish different sections of the code. Conversely, do put an empty line between logical sections in a single function. An example of this is between the type declarations and the first line of actual code. Another example is at the end of a block in curly braces (though this is a judgment call). Long functions that have no blank lines in them are really hard to read.

Use curly braces for the body of all if statements, even if the body is only a single statement. Do the same for else, else if, for, and while statements. The reason for this is twofold: first, it makes the code more readable, and second, it makes it easier to add printf statements for debugging in the body of the expression (which you will frequently have to do).

If you are using a formatting style where the curly braces of a block are on a separate line (which we encourage), make sure that the column of the curly braces match e.g. do this:

instead of:

Don’t put code on the same line as an open curly brace. For instance, this is bad:

Keep the curly braces on their own lines; this makes the code easier to read. Unfortunately, you often see code written like that in books about programming; the reason is that they have to cram as much code as possible onto a single page. You don’t. Instead, write this as:

Put a single space between the keywords if, for, while, or do and the opening parenthesis on the same line e.g. do

and not

The logic is that keywords are not function calls and should not look like them. Similarly, leave a space after return keyword which is followed by an expression.

Do not put an entire block on a single line, and most especially do not put it on the same lines as an if, while, for etc. For instance, change

to

Lines within a block should be indented relative to lines outside a block. Also, don’t indent one space; two spaces is the bare minimum. Four spaces looks nice.

Lines at the same level of a block should start at the same column.

Do not try to do complex calculations in the testing or increment parts of for loops. Don’t try to impress everyone with how clever you are; clever code is a maintenance disaster.

Make variable names descriptive as much as possible; avoid one or two character names unless it’s for something trivial like a loop index. It’s perfectly OK (and usually desirable) to have longer descriptive names for variables. When you do this with names that are actually multiple words, use one of two conventions:

Either convention is OK as long as you’re consistent.

Avoid using implicit int to float or int to double conversions (or vice-versa) as much as possible. It’s hard to keep track of the types of the results otherwise, and C compilers tend not to be very strict about this, which often leads to unexpectedly wrong results. Instead, use explicit type casts when you want to convert an int to a double etc. For instance, this:

should be written as:

Yes, it’s a bit more verbose, but it’s absolutely unambiguous.

This is the single most common style mistake. If a comment is a full sentence, its first word should be capitalized, unless it is an identifier that begins with a lower case letter (never alter the case of identifiers!), and it should end in a period. We prefer comments that are complete sentences. You should use two spaces after a sentence-ending period.

Bad:

Good:

That wasn’t so hard, was it?

When you need to refer to identifiers in the code, put them inside backticks e.g.

(This is a convention borrowed from a format called "markdown"; it looks a bit weird but it’s better than the alternatives.)

If a comment is very short, it doesn’t have to be a full sentence or end in a period e.g.

This is called an "inline comment". Use these only when describing something i.e. in the above code snippet you’re saying "The variable i represents a loop index." (Actually, this comment should probably be omitted altogether, since it should be obvious what the loop index is.)

Comments should be grammatically correct. In particular, incorrect spelling is unacceptable. We hate to sound like your high school English teacher, but it’s a pain to read code with tons of spelling mistakes. Use a spell checker if you have to.

Put a space after the open-comment symbol and before the close-comment symbol i.e. do this:

and not this:

Do not use C++ style comments i.e. comments that start with // and go to the end of the line. It is true that most C compilers (including gcc) accept them, and they are part of the C99 standard. But for this track, don’t use them.

Use this style for multi-line comments:

Most especially, do not use this style:

People who write comments this way may not be aware of the fact that comments can span more than one line. Well, they can, so take advantage of it.

Block comments generally apply to some (or all) code that follows them, and are indented to the same level as that code. Each line of a block comment starts with a * and a single space (unless it is indented text inside the comment). Paragraphs inside a block comment are separated by a line containing a single *. Block comments are best surrounded by a blank line above and below them (or two lines above and a single line below for a block comment at the start of a a new section or function definition). We prefer to start and end block comments with a line containing a single *. In other words, a block comment looks like this:

Write comments for anything that isn’t completely obvious from the context. In particular, write comments for any tricky algorithm or code you are using. When in doubt, comment more rather than less.

Conversely, don’t make completely redundant comments, e.g.

What constitutes redundancy is often a judgment call. If in doubt, comment more rather than less.

Don’t make meaningless comments e.g.

Don’t laugh; we’ve actually seen this sort of thing.

You should almost always put a comment at the beginning of each function describing what it does. The only exception is when you have a series of very similar functions which are written out one after another, and where the first comment applies (suitably modified) to all of them. This kind of "header comment" (not to be confused with header files) is by far the most important kind of comments, because even if the person reading your code has no idea how a given function works, the header comment will at least tell them what it does and how to use it. You should state what each of the arguments represents and what the function returns. You may also want to describe the algorithm used, its efficiency, and any other relevant facts. Here’s an example:

Comments that contradict the code are worse than no comments. Always make a priority of keeping the comments up-to-date when the code changes!

Always indent your comments to the same degree as the surrounding code.

Try to line up inline comments where convenient. In other words, don’t do this:

Instead, do this:

Some people like to line up the close-comment token as well. Use your own judgment.

Do not write comments that apply to the preceding code if you can possibly avoid it. Try to write comments that refer to the current line of code or to the lines of code which immediately follow. For instance, this is bad:

and this is good:

This is really bad:

We hope this is obvious, but we see it in students' submissions all the time. It’s OK to put a comment on the same line as the code, but only if the entire comment will fit on that line e.g.:

If what you have to say won’t fit on the line, put the comment on the lines above the line of code. (Don’t use a very long line to try to fit the comment on one line, of course; see [LINE_LENGTH] above).

Always write function prototypes at the top of a file for every function whose definition is in that file. This is not only good documentation, it enables you to use these functions anywhere in the file without having to worry about putting them in strict definition order. In case you don’t know already, this is a function prototype:

It’s just a function without a body.

Please separate your function definitions by at least two blank lines. Otherwise it’s hard to find where a function definition begins.

Start the line that begins a function in column 0 (the leftmost column).