**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.

Summary

  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) or with delimiter-separated words that use lower case letters and underscores as delimiters?
    • 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.

Format

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

Do

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.

Do

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

And don't

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

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

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.

Miscellaneous

cs-236/style-guide.1484862966.txt.gz · Last modified: 2017/01/19 14:56 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