Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
cs-236:style-guide [2017/01/19 15:46]
egm [Magic Numbers]
cs-236:style-guide [2017/07/11 14:59] (current)
pdiddy [Summary]
Line 25: Line 25:
 #* Are test cases documented with justification and expected output? #* Are test cases documented with justification and expected output?
 # Variables and Constants # Variables and Constants
-#* Are the variables [https://​en.wikipedia.org/​wiki/​Camel_case camelCase] (with the first letter ​lower‐case) or with [https://​en.wikipedia.org/​wiki/​Naming_convention_(programming)#​Multiple-word_identifiers delimiter-separated words] that use lower case letters and underscores as delimiters?+#* Are the variables [https://​en.wikipedia.org/​wiki/​Camel_case camelCase] (with the first letter ​lowercase) or with [https://​en.wikipedia.org/​wiki/​Naming_convention_(programming)#​Multiple-word_identifiers delimiter-separated words] that use lowercase ​letters and underscores as delimiters?
 #* Are the constants all caps with underscores between words? #* Are the constants all caps with underscores between words?
 #* Are variables and constants initialized when they are declared? #* Are variables and constants initialized when they are declared?
Line 33: Line 33:
 #* Are all numbers in the code constants or fit reasonable exceptions? #* Are all numbers in the code constants or fit reasonable exceptions?
 # Functions and Methods # Functions and Methods
-#* Are the names [https://​en.wikipedia.org/​wiki/​Camel_case camelCase] (with the first letter ​lower‐case) or with [https://​en.wikipedia.org/​wiki/​Naming_convention_(programming)#​Multiple-word_identifiers delimiter-separated words] that use lower case letters and underscores as delimiters?+#* Are the names [https://​en.wikipedia.org/​wiki/​Camel_case camelCase] (with the first letter ​lowercase) or with [https://​en.wikipedia.org/​wiki/​Naming_convention_(programming)#​Multiple-word_identifiers delimiter-separated words] that use lowercase ​letters and underscores as delimiters?
 #* Are the parameter names descriptive?​ #* Are the parameter names descriptive?​
 #* Do the functions or methods only do task? #* Do the functions or methods only do task?
Line 40: Line 40:
 #* Are parameters declared as const-references where appropriate to avoid needless copying? #* Are parameters declared as const-references where appropriate to avoid needless copying?
 # Objects and Classes # Objects and Classes
-#* Are class names [https://​en.wikipedia.org/​wiki/​Camel_case camelCase] (with the first letter ​lower‐case)?+#* Are class names [https://​en.wikipedia.org/​wiki/​Camel_case camelCase] (with the first letter ​uppercase for class names)?
 #* Are the names descriptive?​ #* Are the names descriptive?​
 #* Does each class have a default constructor?​ #* Does each class have a default constructor?​
Line 187: Line 187:
 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. ​ 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 = = Test Cases =
 +Test cases strive to ensure correctness in the code. Simple situations should be covered, but more importantly,​ obscure and less common cases need to be considered. For example, when testing a video game, testers do not simply play the game through; instead, they do obscure things such as walk into walls and corners, jump up trees, and cross invisible boundaries. Their goal is to '''​break the code'''​ : they want to find every possible error in the game, expose them, and then fix them. Tests should consider where your code could fail, and then test those areas. ​
  
 +Test cases should include the expected output, and where possible, assert that the program output matches the expected output. It is strongly encouraged, where possible, to write test cases first, with the expected output, before writing the program itself. Also, once the program is written, write additional test cases knowing how the program is written. In other words, use the understanding of the program to '''​break the program'''​ with unexpected inputs. ​
 +
 +Test cases should run automatically. A program should be able to compile or '''​run'''​ in test mode. Test mode runs all tests automatically and reports the test results. Failing tests can then be debugged using the test input. ​
 = Variables and Constants = = Variables and Constants =
 +
 +==== Use camelCase or underscore delimited names ====
 +Variable and parameter names must be written in [https://​en.wikipedia.org/​wiki/​Camel_case camelCase] with the first letter being lowercase or [https://​en.wikipedia.org/​wiki/​Naming_convention_(programming)#​Multiple-word_identifiers delimiter-separated words] that use lower case letters and underscores as delimiters. Which ever style is adopted, be consistent through all the code. 
 +'''​Do'''​
 +<code cpp>
 +//Always use camelCase
 +int numPeople;
 +</​code>​
 +or
 +<code cpp>
 +// Always use underscore delimited
 +int num_people;
 +</​code> ​
 +'''​And don'​t'''​
 +<code cpp>
 +int NumPeople;
 +</​code>​
 +or
 +<code cpp>
 +int numpeople;
 +</​code>​
 +or
 +<code cpp>
 +int numPeople;
 +int num_cars;
 +</​code>​
 +
 +==== Use descriptive names ====
 +Variable names should be descriptive and useful. For code with options, variable names such as “firstOption”,​ “first”,​ “seven”,​ or “optionA” are not useful; to make sense of these names other knowledge is required, which is not discernible from the name alone. Instead, give variables names meaning such as “averageClassSize” or “exitOption”. Furthermore,​ avoid using abbreviations and single‐letter variables; a good practice is to think, ''​Would a random person understand what this variable name represents?''​ Variable names are usually at least two words, except in exceptional cases like indexes (e.g. i, j, or k).
 +'''​Do'''​
 +<code cpp> ​
 +int numberOfBoxes;​
 +char userName;
 +</​code>​
 +'''​And don'​t'''​
 +<code cpp>
 +int boxes; ​
 +int b;
 +char k;
 +char usrKey;
 +</​code>​
 +
 +==== Use constants ====
 +Use const for any variable whose value will not be changing. Constants are written in upper case and underscore delimited (and are usually at least two words, except in a few obvious cases like PI, etc.).
 +'''​Do'''​
 +<code cpp>
 +const int MAXIMUM_WEIGHT = 300;
 +</​code>​
 +'''​And don'​t'''​
 +<code cpp>
 +const int MAXIUMUMWEIGHT = 300; 
 +const int maximumWeight = 300;
 +const int MAXIMUM = 300;
 +</​code>​
 +
 +==== Always initialize at declaration ====
 + ​Always initialize a variable or constant (meaning give it value) when it is first declared.
 +'''​Do'''​
 +<code cpp>
 +int numPizzas = 0; 
 +char userKey = ‘‐’;
 +</​code>​
 +'''​And don'​t'''​
 +<code cpp>
 +int numPizzas; ​
 +char userKey;
 +</​code>​
 +In some cases it will not seem necessary to initialize the variable; however, for example, by initializing numbers to 0 you can avoid potential difficult bugs when code is mistakenly using an uninitialized variable which contains an unpredictable value. Some types, like "​char",​ may not have a canonical agreed upon initial value, but by choosing a consistent initial value, such difficult bugs coming from unpredictable values are avoided. Some types, like strings, are automatically initialized;​ thus, these do not need initialization.
 +
 +====Declare variables at the beginning of their scope====
 +Variables are declared at the top of their enclosing scope (including main) except iterator variables in for loops; for example:
 +<​code>​
 +for (int i = 0; i < MAX_PIZZAS; ++i) {
 +   ...
 +}
 +</​code>​
 +Declare iterator variables in for-statements as shown above except in cases where the iterator variable is needed after the loop.
 +See the functions section below for variable and constant style when there are multiple functions.
 +
 +
  
 = Magic Numbers = = Magic Numbers =
Line 240: Line 324:
 * 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). ​ * 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.  * Variables and constants should be declared at the beginning of the scope in which they are used. 
 +* Functions and methods should assert assumption on parameters. For example, if there is an assumption that a pointer is not null, such an assumption should be asserted: ''​assert (boxPointer != NULL);''​. Or as another example, if an integer parameters is assumed to be positive in the code, such an assumption should be asserted: ''​assert(numCars > 0);''​. Asserting assumptions is another form of self-documenting code and helps others use the code as it was intended by the original author. ​
  
 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.  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. 
cs-236/style-guide.1484866013.txt.gz · Last modified: 2017/01/19 15:46 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