All courses in our department, from CS1 to Software Engineering, require you to create programs that are not only functional but well designed. Below you will find our coding standards for all courses.
Our number one guideline: 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 )
- Alternatively, for Java, you may use the JavaDoc convention of @param and @return in place of preconditions and postconditions.
- 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.
- 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.
- In NetBeans, you can press SHIFT + CTRL + F to autoformat. You can also change the autoformatting rules in the preferences.