This style guide will evolve over the course of the semester, as we learn more constructs and concepts (and as I encounter common mistakes in student code).
Q: Why should you care about style?
Short answer: I will take off many, many points when you submit unreadable programs.
Long answer: style is important. When you get into the workforce, most software houses will have fairly rigid standards for how code is to be written. If you write ugly code, you will get fired (or, at least, get smaller bonuses). More importantly, good style makes code more readable and modifiable, and hence maintainable. The badly written software of today is the maintenance disaster of tomorrow. So save the world and write nice code.
Contents:
- Sample program(s)
- Choosing identifiers
- Comments
- Indent and brace style
- Formatting complex code
- Other style resources
A sample program
Sometimes the best way to learn is to look at someone else's code. I present sample.c, a short program I wrote up with voluminous comments on style. I recommend you save and open this file in an environment (such as Visual C) that has syntax coloring, as it helps immensely in reading.
You may want to look at solution code for the NAW server project we've been doing in class for further style examples-- particularly declaration of functions.
Choosing identifiers
Choosing names for variables and constants is not a science; it's a matter of taste and judgment, and you really only get good at it through practice and careful consideration. Fortunately, over time, programmers have agreed on some common guidelines:
Typographic conventions in C:
Other languages have other cultures with different conventions, but since we're working in C, these are fairly well-agreed upon:
- Name your constants in UPPERCASE.
- Name your variables in all lowercase.
- Separate words in multi-word identifiers using the underscore character _.
- Don't begin or end variables with an underscore except in special cases. (What special cases? If you have to ask, you don't need to know.)
- Name related variables using similar prefixes if it makes sense: coeff_first, coeff_second, coeff_third.
Length
Identifiers that are too short are obviously bad (x, y, qxp, etc.) unless you're implementing some very well-known mathematical formula (y = mx + b, for example), and even then you probably want to comment their declarations.
On the other hand, choosing many identifiers that are more than a dozen or so characters long usually will make your program harder to read, not easier. Therefore, try to think hard about variable names that are both expressive and compact.
Design considerations
Sometimes, if you have names that are too long, it indicates a flaw in your design: perhaps you should move some segment of code into a separate function, where context would eliminate the need for long identifiers?
Comments
Comments basically come in four kinds. In order of decreasing average size:
- Introductory comment: A big comment at the top of your file, containing various meta-information about the program. See the sample program(s) above for examples.
- Banner comment: A wide comment, frequently with attention-getting ornamentation, that marks the beginning of an important section of the file. This makes it easy to skim a source file for the section you're looking for. Example:
/* ------------------------------- * * CONSTANTS SECTION * ------------------------------- */ #define FOO 123456789- Block comments: A multi-line comment used to explain the purpose of a series of statements immediately following it. Block comments are often also used to document functions. Example:
/* Evaluate the quadratic. a, b, and c now represent the square, linear, and constant coefficients, respectively. */ result = a * x * x; result = result + b * x; result = result + c;- One-liners: Very short comments that clarify some minor point. Often used for variable declarations, e.g.:
double integral_coeff; /* Coefficient of the new integral */ double growth_deriv; /* Growth curve derivative. */Don't feel that all your comments must fit in these four categories, but in practice they usually do.
By the way, writing comments is a good mental exercise that helps you organize your thoughts about the code. When I'm writing a particularly complicated or subtle function, sometimes I'll sit down and write out a series of comments (first let's do this; then we do this; finally, if X, then do this.) before I even write the code. I then go back and fill in code below each comment to implement what I intended.
P.S.: You can't put a comment inside another comment!
Braces and indent style
There are several brace/indent styles, stemming from cultural differences among C programmers, and choosing among them is basically a matter of taste. The important thing is to be consistent. Pick a style, and do not deviate. The two most common brace styles I have seen are as follows:
- Opening brace on the same line as its controlling statement (if, else, etc.), and closing brace on its own line after all enclosing statements, vertically aligned with the controlling statement:
if (x < 0) { printf("X is negative.\n"); } else { printf("X is non-negative.\n"); }- Opening brace and closing brace both on their own lines, vertically aligned with the controlling statement:
if (x < 0) { printf("X is negative.\n"); } else { printf("X is non-negative.\n"); }In these examples, I indent 4 spaces. I find that most readable; your mileage may vary, but always indent at least 2 spaces at each level, and not more than 8. Don't use varying widths: pick a number of spaces and stick with it.
See also: the Jargon File's entry on indent style.
Formatting complex code
"Complicated" is never a compliment among programmers. Don't write long, complicated lines of code if you can help it. Instead, break complicated computations up into multiple lines. If this means you have to declare more variables and store subexpressions in these variables, do it, e.g.:
/* Bad. */ quadratic_eval = (coeff_first*input*input)+(coeff_second*input)+(coeff_third*constant); /* Good. */ term_a = coeff_first * input * input; term_b = coeff_second * input; term_c = coeff_third * constant; quadratic_eval = term_a + term_b + term_c;Notice also that I used spaces liberally in my code. The second is easier to read.
Other style resources
(in progress)