School of Engineering and Applied Science Department of Computer Science CSci 49 -- Introduction to C Computing http://www.seas.gwu.edu/~csci49/spring06 Prof. Michael B. Feldman  mfeldman@gwu.edu

Introduction

Style Guidelines

A. Identifier Naming

1. Use identifiers that have meaning in the particular problem. Do not use single letter names such as a or i unless the single letter has problem-specific meaning.
2. Make identifiers easy to read. For example, use currentValue instead of curval.
3. Keep identifiers to a reasonably short length.

B. Identifier Case

1. Use UPPERCASE for constants.
2. Use TitleCase for class, package, and interface names.
3. Use lowercase for variable and function names, except for the first letter of each word other than the first word. For example, minTaxRate. Note that C requires all reserved words to be lowercase.

C. Indentation and use of braces ({})

1. Indent the code in any block by two or three spaces. Be consistent! If you prefer two spaces, use two spaces for indentation throughout your code. Note that code from the book uses three space indentation, but Prof. Feldman's uses two.
2. When modifying code from the book or from Prof. Feldman, you must remain consistent to the original coder's style OR you must change all of the original spacing to match your own style.
3. In a switch statement, indent each case label two or three spaces. Indent all code associated with a case two or three additional spaces.
4. Do not use the tab key for indentation; use the space bar instead.
5. Put the left brace ({) starting each new block on a new line. Line up the opening left brace, and the corresponding right brace (}) with the first letter of the associated reserved word (while, if, else, switch, etc.). For example:

while(value < 25)
{
  value = value 5;
  printf ("The value is %d\n", value);
}
 

6. We require braces on the body of every if, else, while, and for statements, even if that body contains only a single statement. This is to make it easier to add a statement to a block, or to remove a statement from one. For example, C would allow
 


if (x == 1)
  y = 5;
else
  z = 10;

but we require

if (x == 1)
{
 y = 5;
}
else
{
 z = 10;
}

and will grade accordingly. This might seem like a lot of extra work, but it pays off later. To see this, consider adding the statement p = 4; to the block containing y = 5; In the first case, you'd have to remember to add braces; in the second case, the braces are already there, so just add the statement!

7. Put the left brace ({) starting each new block on a new line. Line up the opening left brace, and the corresponding right brace (}) with the first letter of the associated reserved word (while, if, else, switch, etc.). For example:

while (value < 25)
{
  value = value 5;
  printf ("The value is %d\n", value);
}


Note: the examples in the book are written like:


while (value < 25){
  value = value 5;
  printf ("The value is %d\n", value);
}

This is acceptable, but makes it much more difficult to check that your left and right braces are balanced.


8. The single exception to the bracketing rule is an if statement(s) that is nested inside an else block. You may, as a personal style choice, write nested if statements in the style of either example A or example B. Notice that example A and example B are logically identical.

 

EXAMPLE A	EXAMPLE B
if (x < 5) {   y = 9; } else {   if (x > 25)   {     y = 100;   }   else   {     y = 0;   } }	if (x < 5) {   y = 9; } else if (x > 25) {   y = 100; } else {   y = 0; }

D. Spacing

1. Carefully use white space to draw attention to appropriate features of a program, but do not put excessive amounts of white space between blocks. Usually one or two lines will make the division clear.
2. Put one space after each comma in a parameter list (a, b, c, d, e).
3. Put one space on either side of a binary operator (x < 7).
4. Do not put spaces immediately after a left parenthesis or before a right parenthesis. Write (noName), not ( noName ).
5. Do not put spaces before a semicolon.

E. Messages and Prompts

1. Do not condescend.
2. Do not let humor obscure your meaning or insult the user or reader of your code.
3. Be informative, but succinct.
4. Define specific input options in prompts when appropriate.
5. Specify default selections in prompts when appropriate.

F. Output

1. Label all output clearly.
2. Present information to the user in a consistent manner.

Documentation Guidelines

A. The Reader

1. Write all documentation as if the reader is computer literate and basically familiar with the C language.
2. Assume the reader knows almost nothing about what the program is supposed to do.
3. Remember that a section of code that seems intuitive to you when you write it might not seem so to another reader or to yourself later. Document accordingly.

B. Content

1. Make sure comments are accurate.
2. Keep comments updated as changes are made to the code.
3. Be concise but thorough.

C. Header Blocks

1. Every source code file should contain a header block of documentation providing basic information about the contents and the author. In this course, we prefer the following form:
   

D. In-Line Comments

1. Use in-line documentation as appropriate to clearly describe interesting processing.
2. Put a comment on the same line with code only if the comment applies to one line of code and can fit conveniently on that1line. Otherwise, put the comment on a separate line above the line or section of code to which it applies.

E. Miscellaneous

1. Don't wait until a program is finished to insert documentation. Document as you go -- it will help you understand your own program, and you won't be writing documentation too close to the deadline.