Coding Standards

All courses in the Computer Science Department require students to create programs that are not only functional but well-designed. The following document lays out a standard for all courses in the department from CS1 to Software Engineering.

Above all else, the number one guideline is do not comment your code - code your comments!

Naming Rules:

1. Every variable should be given a descriptive name — examples: myAge, response, menu_choice 
2. Function names should contain verbs — examples: computeAverage, getUsersName 
3. Function names should also obey “Camel Case” where the first word is all lower case and each subsequent word begins with an uppercase letter — examples: getUsersName(), isAvailable()
4. Variable names must be in a consistent style; the dominant conventions are:
   • Camel Case (e.g. myAge, myStartDate)
   • all lower case with underscores (e.g. my_age, my_start_date)
5. Constants should be written with all uppercase letters with words separated by underscores. All uppercase is reserved for constants only — examples: MAX_SIZE, FEET_IN_MILE

Commenting Rules:

1. Every file should have a comment header that contains the following: name of student, due date of project, course code (e.g., CSC1610), and brief description of the goal of the file.
   
   Example:
   // Project1.cpp
   // Author: Zach Kissel
   // Date: 2/29/13
   // Course: CSC1610
   // Description: This program takes a length and width from the user as input and determines and displays the area of the rectangle. 
2. Every function should be preceded by a comment that describes what the function does, and states the preconditions of the function and the postconditions of the function.
   
   Example:
   // This function determines whether a character is a vowel.
   // Precondition: ch is a letter
   // Postcondition: returns true if ch is a vowel, false otherwise. 
   bool isVowel( char ch ) 
   { 
     …
   } 
3. Every variable and constant declaration should have comment (on the same line) saying what that variable or constant is for; this must supply information other than the data type.
   
   Example
   int ssn; // the user’s social security number 
4. Every major block of code should have a comment that describes what the following lines of code will do. Comments should be free of spelling mistakes and grammatical flaws.

Spacing Rules:

1. There should be one blank line between each major block of code. 
2. Blocks of code (in C-based languages, surrounded by curly brackets/braces) must always be indented a minimum of 3 spaces from the surrounding code. 
3. Indentation must be consistent; code at the same level of nesting must have the same level of indentation, and indentation cannot change from block to block for no reason. 
4. There should only be one variable or constant declaration per line.

Length Rules:

1. As a rule of thumb functions should be concise and do one thing and that one thing well. 
2. A colloquial phrase is a function should not be any longer than a screen full of code.
3.  A line of code should not be overly long (e.g., greater than 80 characters wide)

Control Structures:

1. The control structure itself must determine the flow of the program. This means that a loop’s boolean expression should encompass all possibilities for continuing the loop or stopping. 
2. The use of a break, or a goto, should never jump out of a loop, or a branch (if/else). The only place “break” should be used in a C-like language is in switch/case, where it is necessary. 
3. Braces beginning or ending a control structure should appear on a line all by themselves.

Output Rules:

1. All output should be clear and concise.
2. All output should be free of spelling and grammatical errors.

Class Rules:

1. Class names should be as descriptive as variable names. 
2. Data members of a class must be private or protected; make use of accessor methods (get and set) to operate on attributes outside of the class. 
3. Methods should follow the naming and commenting guidelines of functions. 
4. If a method is only used within the class, make the method private.

Formatting Tips in Common IDEs:

1. In Microsoft Visual Studio 2010 you can autoformat the entire source file using the shortcut: CTRL + k + d. 
2. In Microsoft Visual Studio 2010 you can autoformat a region of source code by highlighting the region and using the shortcut: CTRL + k + f.
3. In Eclipse you can autoformat the entire source file using the shortcut: SHIFT + CTRL + F In Emacs you can autoformat a selected region with ESC + q.