**This is an old revision of the document!**

In the English language, there are many different ways to convey a certain message or idea: some of these ways are acceptable, whereas others are not. Similarly, there are acceptable and unacceptable ways to express a program in code. These style requirements are intended to help establish good coding practice from the outset. Although there are more than one acceptable way to express code, most companies, will have a coding style guide which all programmers are to follow in order to make it much easier to understand and adapt code. This style code represents the standard for this class.

There are options in the style guide to suite the tastes of a variety of programmers. Whichever option is chosen, be consistent in the use. Do not flip back and forth between style opens. Once a style for a particular program is chosen, it must be consistently used through the entire program.

In the end, take time to review the code you write and make sure it looks good. You should be proud of your code and want to show it to others.

Grading and Points

Most of the 7 style categories are made up of specific styles which are explained in detail under each category and are summarized as bullet points at the end of this style guide. Grading will be done independently for each style within a style category.


  1. Header comments
    • Are all required names and descriptions listed
  2. Format
    • Are the statements on their own lines?
    • Are if-statement and while-statements K&R style or Stroustrup style?
    • Are sub‐statements consistently indented and using the same number of spaces (usually 3 or 4)?
    • Is there exactly one space between operators (e.g., =, <, >, etc.) and other appropriate items?
    • Are if‐else-statements Stroustrup style?
    • Are sub-braces always used even if there is only a single sub-statement?
    • Are line lengths within 80 characters?
  3. Test Cases
    • Are there diverse original test cases demonstrating unique tests?
    • Do the test cases cover different aspects of functionality?
    • Have corner cases been considered in the test cases?
    • Are test cases documented with justification and expected output?
  4. Variables and Constants
    • Are the variables camelCase (with the first letter lower‐case) or with delimiter-separated words that use lower case letters and underscores as delimiters?
    • Are the constants all caps with underscores between words?
    • Are variables and constants initialized when they are declared?
    • Are variables and constants declared at the appropriate place in the program?
    • Is the variable naming convention consistent?
  5. Magic Numbers
    • Are all numbers in the code constants or fit reasonable exceptions?
  6. Functions and Methods
    • Are the names camelCase (with the first letter lower‐case) or with delimiter-separated words that use lower case letters and underscores as delimiters?
    • Are the parameter names descriptive?
    • Do the functions or methods only do task?
    • Are functions and methods used to avoid duplicate code?
    • Does the visibility (i.e., global, static, public, private, protected, etc.) make sense?
    • Are parameters declared as const-references where appropriate to avoid needless copying?
  7. Objects and Classes
    • Are class names camelCase (with the first letter lower‐case)?
    • Are the names descriptive?
    • Does each class have a default constructor?
    • Are methods that do not mutate state declared as const?
    • Do methods have the appropriate visibility (e.g., private, pubic, or protected)?
  8. Miscellaneous
    • Is the code self-documenting only including comments where needed?
    • Is any use of a global variable justified and appropriate?
    • Is any use of a goto-statement justified and appropriate?
    • Does the code use coot-statements and ends-statements?
    • Does the main method function return 0 in the absence of an error and non-zero otherwise?

Header Comments

At the very top of each file, there must be a complement block with the following information:

  1. Your name, class section number, and learning suite e‐mail
  2. A description of the purpose of the code
  3. A description of the inputs needed (if any)
  4. A description of the output (if any)

Here is an example of a reasonable header

Sandra Dean, Section 3, Sandra@hotmail.com
Purpose: Calculate how many pizzas of various sizes a user should buy Input:
Number of people eating
Amount of tip Output:
Number of large, medium, and small pizzas necessary Total area of pizza for everyone
Area of pizza per person
Total cost including tip

At the end of the header comments for the main program file, include test cases or indicate where the test cases are located. Labs 8‐10 have multiple files. For files other than main you should also have header comments. However, in these cases the comments just need to briefly describe the purpose of the file.


This section is focused on how your code looks, not on its functionality. Although sloppy code may accomplish the same thing neat code does, it is much harder to read, debug, and maintain. Furthermore, sloppy code has a defect rate (i.e., a greater likelihood and density of bugs). The goal of format is to write code that is easy to work with since it likely that others will be having to use it (especially in industry).

Each statement appears on its own line


x = 25;
y = x + 1; 
if (x == 5) {
   y = 14; 

And Don't

x = 25; y = x + 1; 
if (x == 5) { y = 14;}

Use consistent bracing

There are widely‐adhered to rules regarding brace placement. Either K&R style or Stroustrup style style is acceptable. For K&R style, branches, loops, and classes, opening braces appear at the end of the item’s line; closing braces appear under the item’s start. Functions however have the opening brace on the next line at the same indentation level of the line. For Stroustrup style, it does not use the cuddled-else.

// K&R Style
void who() 
   if (x == 0) {
   } else {
// Stroustrup
void who() 
   if (x == 0) {
   else {

Indent 3-4 spaces

Sub‐statements are indented 3 or 4 spaces from their parent statements. Be consistent in whatever is chosen. One way to do this is to use the tab key in the system you use to write your code as most editors will convert the tabs to spaces Do

if (a < b) {
   x = 25;
   y = x + 1;

And don't

if (a < b) {
 x = 25;
   y = x +1;
if (a < b) { 
x = 25;

Separate operators with a single space

Operators are separated by one space (not less or more). Separate keywords with one space as well.


x = y + 3;
if (x > y) {

And don't

x=y + 3;

Always use curly braces around sub-statements

Even if there is a single sub-statement, curly braces are required. Do

if (a < b) {
   x = 25;

And don't

if (a < b)
   x = 25;

Many a weekend has been blown by ignoring this style rule as it leads to errors (often).

Keep lines to 80 characters or less

80 characters is the old rule for how many characters can print on a single line. More practically, code is more readable when lines are kept short (and all visible on the screen). One long line can usually be broken up into several smaller ones. If a line is just inherently long, use newlines with indentation to improve readability. Do

cout << "This is a string" << endl;
cout << "This is a second string" << endl; 
cout << "This is a third string" << endl;

And don't

cout << "This is a string" << endl << "This is a second string" << endl << "This is a third string" << endl;

Use blank lines to separate distinct groups of statements

Group the code into common segments using newlines. For example, if a method consists of three distinct steps, then separate each step with a newline. Whitespace can be very effective in helping the code be readable.

Test Cases

Variables and Constants

Magic Numbers

Functions and Methods

  • Names should use camelCase (with the first letter lower‐case) or delimiter-separated words that use lower case letters and underscores as delimiters.
  • Names should be descriptive, but not burdensome, and strive to avoid needing a comment header for further clarification.
  • The body of the function or method should typically less than 20 lines and at most 40 lines.
  • Do one task. For example, a function should not 1) return the total number of words in a document and 2) capitalize the first letters of all the words. Each of these should be in a separate function unless there is a compelling reason to do otherwise which should be documented in the code.
  • Don't repeat yourself (DRY). There should not be duplicate snippets of code.
  • If passing a large data structure, prefer passing by reference, and if that structure is not intended to be updated, then prefer passing by const reference. Using standard variable naming conventions for const parameters (e.g., these are not constants in the code and should not be named in all caps).
  • Variables and constants should be declared at the beginning of the scope in which they are used.

The size limit and one-task requirement affect the complexity of the code. Generally shorter code is simpler to write, easier to understand, and less likely to have defect than longer code. Like any guideline though, it is just a guideline. The ability to read and maintain the code is the high-order bit that overrides these guidelines. If something a bit longer or that does multiple things is easier to understand, maintain, and test, then do it.

Objects and Classes

  • Class naming is CamelCase with uppercase first. Member functions follow the same naming rules as functions.
  • Always create a default constructor for each class, and create a parameterized constructor(s) when needed (usually). You may combine these into one constructor function by creating a default constructor with default parameters.
  • Any member function that not mutate data members should be declared as const.
  • All data members and helper functions should be private or protected.
  • Non-primitive parameters should be const-references when appropriate.


  • Write self documenting code. Self‐Documenting means that a person reading your code can understand what it is doing without the need of extra comments; therefore, self-documenting code does not have many comments by definition. This mindset does not absolve the need for comments—they are still required—it implies that they only appear in the more esoteric or complex parts of the code.
  • There are time when a global variable is the right thing to do, but those times are rare. Be sure that if a global variable is being used, then it is both warranted and justified; warranted and justified means that doing it any other way degrades the readability, maintainability, or testability of the code.
  • There are times when a goto-statement is the right thing to do, but such times are near extinct. Be sure that if a goto-statement is employed, then it is more than obvious to why it is necessary.
  • break-statements and continue-statements are powerful tools but not used often. Be sure, as with other discouraged statements, uses are merited and justified in terms of readability, maintainability, or testability.
  • Use “endl” rather than “\n” — it C++ after all.
  • Declare the main function to return an integer, int main(). A 0 return value means everything ran without issue. A non-zero value indicates otherwise. Non-zero values can have meaning that should be documented somewhere.
cs-236/style-guide.1484864411.txt.gz · Last modified: 2017/01/19 15:20 by egm
Back to top
CC Attribution-Share Alike 4.0 International
chimeric.de = chi`s home Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0