**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” or “Stroustrop” style is acceptable. For K&R branches, loops, functions, and classes, opening braces appear at the end of the item’s line; closing braces appear under the item’s start. For Stroustrop, the first brace is place on the next line under the item's start. Do not use any other style. Also, once you choose one style for your lab, use that same style throughout! In the style sections which follow, we will use “K&R” style when showing braces, but know that in all those cases “Stroustrup” style would also be fine.

Test Cases

Variables and Constants

Magic Numbers

Objects and Classes

Miscellaneous

cs-236/style-guide.1484858565.txt.gz · Last modified: 2017/01/19 13:42 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