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!
- Every variable should be given a descriptive name — examples: myAge, response, menu_choice
- Function names should contain verbs — examples: computeAverage, getUsersName
- 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()
- 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)
- 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
- 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.
// Author: Zach Kissel
// Date: 2/29/13
// Course: CSC1610
// Description: This program determines and displays the area of the rectangle.
// Input: The width and the length (the sides) of the rectangle
// Output: width * length, the Area of the rectangle
- 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.
// 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 )
- 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.
int ssn; // the user’s social security number
- 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.
- There should be one blank line between each major block of code.
- 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.
- 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.
- There should only be one variable or constant declaration per line.
- As a rule of thumb functions should be concise and do one thing and that one thing well.
- A colloquial phrase is a function should not be any longer than a screen full of code.
- A line of code should not be overly long (e.g., greater than 80 characters wide)
- 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.
- 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.
- Braces beginning or ending a control structure should appear on a line all by themselves.
- All output should be clear and concise.
- All output should be free of spelling and grammatical errors.
- Class names should be as descriptive as variable names.
- 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.
- Methods should follow the naming and commenting guidelines of functions.
- If a method is only used within the class, make the method private.
Formatting Tips in Common IDEs:
- In Microsoft Visual Studio 2010 you can autoformat the entire source file using the shortcut: CTRL + k + d.
- In Microsoft Visual Studio 2010 you can autoformat a region of source code by highlighting the region and using the shortcut: CTRL + k + f.
- 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.