wiki:CodingStandardsDesirable
Last modified 10 years ago Last modified on 12/22/2009 05:48:52 PM

from DRAFT Parasoft C++Test Use

DRAFT WORKING DOCUMENT C++ Desirable Coding Standards Rules DRAFT WORKING DOCUMENT

Introduction

This document will track the identification and/or implementation of Parasoft C++Test Rules for desirable LSST C++ Coding standards. Companion documents include:

The document is organized according to the LSST Data Management: C++ Programming Style Guidelines

General Recommendations

  • 2-1 We are writing code for humans to read, not computers
    • -
    • Mod: NA

  • 2-3 The rules can be violated if there are valid, documented reasons to do so and they are approved by peer review.
    • -
    • Mod: NA

  • 2-4 Use object orientation in your programs
    • -
    • Mod: Could include all OOP Parasoft Rules under this.
  • 2-4-a Do not just code C style in C++
    • -
    • Mod: NA

  • 2-4-b Avoid overly complex inheritence hierarchies, more than 3 levels should be a warning sign (except in Frameworks)
    • Class inheritance level [METRICS-05-3]
    • Mod:
    • Installed 3 Sep 2009 as LsstDm-2-4b from METRICS-05 which change to allowable # of levels.

  • 2-4-c Use inheritance to specialize behavior for the same or similar data, use template to specialize data for the same behavior.
    • -
    • Mod:

  • 2-4-d Avoid multiple inheritance, only use when it is for completely distinct/disjoint considerations.
    • Do not use multiple inheritance [OOP-05-2]
    • Mod: tone down severity level
    • Installed 3 Sep 2009 as LsstDm-2-4d from OOP-05

  • 2-4-e You may overload member functions but try to do so only where required (virtual functions) or you need to vary the parameter list.
    • Do not derive functions with the same name from more than one base class [OOP-04-3]
    • Mod: needs work

  • 2-4-f Keep functions short and with a single purpose.
    • Follow the Cyclomatic Complexity limit of 10 [METRICS-18-3]
    • The length of a macro should not exceed 10 lines [FORMAT-05-3]
    • Any one function (or method) will contain no more than 200 logical source lines of code (L-SLOCs) [JSF-1-3]
    • Avoid functions with over 50 lines [METRICS-01-5]
    • Avoid source files that are longer than 500 lines [METRICS-24-5]
    • Mod: determine what is short and purposeful
    • Installed 3 Sep 2009 as LsstDm-2-4f from METRICS-18-3

Naming Conventions

General Naming Conventions

  • 3-7 Names representing template types may be a single uppercase letter or a mixed case phrase, first letter capitalized in each word, indicating the desired type.
    • -
    • Mod: implement

  • 3-9 Global variables should be avoided and if used always be referred to using the '::' operator. (Also required)
    • Global prefixes should only be used for global variables [NAMING-04-3]
    • Mod
    • Installed 3 Sep 2009 as LsstDm-3-9 from NAMING-04

  • 3-11 Generic variables can have the same name as their type.
    • -
    • Mod: implement

  • 3-13 Variables with a large scope should have long names, variables with a small scope can have short names.
    • -
    • Mod: implement, maybe

  • 3-14 The name of the object is implicit, and should be avoided in a method name.
    • -
    • Mod: implement

Specific Naming Conventions

  • 3-16 The term 'compute' should be used in methods where something is computed.
    • -
    • Mod: consider

  • 3-17 The term 'find' should be used in methods where something is looked up.
    • -
    • Mod: consider

  • 3-18 The term 'initialize' should be used where an object or a concept is established.
    • -
    • Mod: consider

  • 3-19 Variables representing GUI components should be suffixed by the component type name.
    • -
    • Mod: consider

  • 3-20 The suffix List can be used on names representing a list of objects.
    • -
    • Mod: implement

  • 3-21 The prefix 'n' should be used for variables representing a number of objects.
    • -
    • Mod: consider

  • 3-22 The prefix i should be used for variables representing an entity number.
    • -
    • Mod: consider

  • 3-23 Iterator variables should be called i, j, k etc and should be declared within the loop scope.
    • -
    • Mod: implement

  • 3-24 The prefix 'is' should be used for boolean variables and methods.
    • Functions that begin with 'is' should return boolean values [NAMING-20-3]
    • Begin all boolean type variables with 'b' [NAMING-08-3]
    • Mod: fix
    • Installed 9 Oct 2009 as LsstDm-3-24a from NAMING-08 with modifications to support 'is'
    • Installed 9 Oct 2009 as LsstDm-3-24b from NAMING-20 with modifications to support 'is', 'has', 'can', 'should'

  • 3-26 Abbreviations in names should be avoided.
    • -
    • Mod: implement

  • 3-29 Enumeration constants can be prefixed by a common type name.
    • -
    • Mod: implement

  • 3-30 Exception classes should be suffixed with Exception.
    • -
    • Mod: implement

  • 3-31 Functions (methods returning something) should be named after what they return and procedures (void methods) after what they do.
    • -
    • Mod: NA

  • 3-32 Parameters in functions should be declared in order of output, input, default input.
    • -
    • Mod: implement

Files

Source Files

  • 4-2 Files that contain a single class should have the name of the class, including capitalization.
    • An include file for a class should have a file name of the form <class name> + extension [NAMING-32-3]
    • Mod: fix .hh -> .hpp
    • Install 3 Sep 2009 as LsstDm-4-2 from NAMING-32

  • 4-3 Member functions and data should be listed logically.
    • -
    • Mod: NA

  • 4-4.a All non-templatized class/function definitions except inlines should reside in source files.
    • -
    • Mod: implement

  • 4-7 Special characters like TAB, carriage-return (ctrl-M) and page break should be avoided.
    • Tabs that do not use ASCII spaces shall not be used [FORMAT-01-5]
    • Only those escape sequences that are efined in ISO/14882:2003 shall be used [CODSTA-CPP-60-3]
    • Mod: fix
    • Installed 3 Sep 2009 as LsstDm-4-7a from FORMAT-01 for <tab> check
    • Installed 3 sep 2009 as !LsstDM-4-7 from CODSTA-CPP-60 to disallow most escape sequences.

Include Files and Include Statements

  • 4-10 Include statements should be sorted and grouped.
    • -
    • Mod: NA

  • 4-14 There should be a header file for each library that has the name of the library and includes all of the include files necessary to define the public interface.
    • -
    • Mod: maybe?

  • 4-15 Delimit only system include file paths with '<>'
    • Mod: maybe if have table list of all headers

Statements

Types

  • 5-1 Types that are local to a single .cc file only should be declared inside that file.
    • Declare variables as locally as possible [OPT-01-3]
    • Variables will not be introduced until they can be initialized with meaningful values [OPT-26-2]
    • Mod: implement

Variables

  • 5-4 Variables should be initialized where they are declared.
    • Initialize all variables [INIT-03-3]
    • Variables will not be introduced until they can be initialized with meaningful values [OPT-26-2]
    • Mod: implement
    • Installed 3 Sep 2009 as LsstDm-5-4 from Opt-26 with on description change.

  • 5-5 Multiple assignment should be used only with a constant type.
    • Do not assign incompatible variable types [PB-06-3]
    • Mod: implement

  • 5-7 Use of global variables should be minimized.
    • Global prefixes should only be used for global variables [NAMING-04-3]
    • Avoid using global data in member functions [OOP-10-2]
    • Avoid using global variables, global functions, and class in file outside namespaces [CODSTA-CPP-36-3]
    • The global namespace shall only contain main, namespace declarations and extern "C" declarations [MISRA2008-7_3_1-3]
    • Mod: implement
    • installed 3 Sep 2009 as LsstDm-5-7 from NAMING-04 as template.

  • 5-9 Related variables of the same type can be declared in a common statement.
    • -
    • Mod: NA

  • 5-10 The 'const' keyword should be listed after the type name.
    • -
    • Mod: implement

  • 5-11 Implicit test for 0 should not be used other than for boolean variables.
    • Tests of a value against zero should be made explicit, unless the operand is effectively Boolean [MISRA2004-13_2-3]
    • Mod:
    • Installed 3 Sep 2009 as LsstDm-5-11 from MISRA2004-13_2
  • 5-12 Floats and doubles should never be directly tested for equality.
    • Floating-point expressions shall not be tested for equality or inequality [MISRA2004-13_3-3]
    • Mod: implement
    • Installed 4 Sep 2009 as LsstDm-5-12 from MISRA2004-13_3

  • 5-13 Variables should be declared in the smallest scope possible. Variables should be initialized when declared (and not declared before they can be initialized).
    • Initialize all variables [INIT-03-3]
    • Declare variables as locally as possible [OPT-01-3]
    • Mod: implement
    • Installed 3 Sep 2009 as LsstDm-5-13 from Opt-01

Loops

  • 5-15 Loop variables should be initialized immediately before the loop.
    • Covered by Rule !LsstDM-5-15

  • 5-16 'do-while' loops can be avoided.
    • Prefer while statements over do statements [CODSTA-18-5]
    • Mod: implement
    • Installed 3 Sep 2009 as LsstDm-5-16 from CODSTA-18

  • 5-17 The use of 'break' and 'continue' in loops should be avoided.
    • The continue statement shall not be used [MISRA2004-14_5-3]
    • Do not use break in for loops [CODSTA-08-2]
    • Do not use the break statement [JSF-191-2]
    • Do not use the break statement [MISRA-058-3]
    • The continue statement shall not be used [JSF-190-2]
    • Mod: implement

  • 5-18 The form 'while(true)' should be used for infinite loops.
    • -
    • Mod: implement

Conditionals

  • 5-19 Complex conditional expressions should be avoided. Introduce temporary boolean variables instead.
    • Separate logical tests in conditional expressions [FORMAT-31-3]
    • Mod: implement

  • 5-20 The nominal case should be put in the 'if' -part and the exception in the 'else' -part of an 'if' statement.
    • 'if' and 'else' should be followed by a compound statement [MISRA2004-14_9-3]
    • Mod: maybe

  • 5-21 The conditional can be put on a separate line.
    • -
    • Mod: implement

Methods / Functions

  • 5-24 Arguments that are of non-primitive types and will not be modified should be passed by 'const' reference.
    • Declare reference parameters as const references whenever possible [CODSTA-CPP-43-3]
    • Declare parameters or local variable as const whenever possible [CODSTA-CPP-53-3]
    • Mod: implement
    • Installed 4 Sep 2009 as LsstDm-5-24 from CODSTA-CPP-43

Constructors and Destructors

  • 5-29 Destructors should be declared virtual.
    • Define a virtual destructor in classes used as base classes which have virtual functions [JSF-78-2]
    • Define a virtual destructor in classes used as base classes which have virtual functions [OOP-22-1]
    • Make destructors virtual in base classes [OOP-24-1]
    • Mod: unchanged
    • Installed 4 Sep 2009 as LsstDm-5-29 from OOP-24

Miscellaneous

  • 5-30 The use of magic numbers in the code must be avoided.
    • Avoid magic numbers [CODSTA-26-3]
    • Avoid magic numbers [JSF-151-3]
    • Mods:
    • Installed 26 Aug 2009 LsstDm-5-30 from CODSTA-26
  • 5-31 Floating point constants should always be written with decimal point and with at least one decimal.
    • -
    • Mod: implement

  • 5-32 Floating point constants should always be written with a digit before the decimal point.
    • -
    • Mod: implement

  • 5-33 goto should not be used.
    • The goto statement shall not be used [JSF-189-3]
    • The goto statement shall not be used [MISRA2004-14_4-3]
    • Mod: should vs shall, implement
    • Installed 4 Sep 2009 as LsstDm-5-33 from MISRA2004-14_4

  • 5-35 Signed int should be the preferred type for indices, even those in which a negative value is illegal.
    • Unsigned arithmetic shall not be used [PB-25-2]
    • Do not use floating point variables as loop counters [JSF-197-2]
    • Do not use floating point variables as loop counters [MISRA-065-3]
    • Mod: added unsigned varaibles in additional to floats.
    • Installed 4 Sep 2009 as LsstDm-5-35 from MISRA-065 modified for unisgned, too

  • 5-37 Minimize use of 'define' statement.
    • Do not define constants via #define [CODSTA-03-3]
    • Do not define constants via #define [JSF-30-2]
    • Do not use a #define that prevents the compiler from checking types except ones used only in #ifs and #elifs conditions [CODSTA-37-3]
    • Do not use a #define that prevents the compiler from checking types [CODSTA-38-3]
    • Mod:
    • Installed 4 Sep 2009 as LsstDm-5-37 from CODSTA-37
  • 5-38 No code should be commented out; use a preprocessor directive to include or inhibit code use.
    • Sections of code should not be "commented out" [JSF-127-2]
    • Sections of code should not be "commented out" [MISRA2004-2_4-4]
    • Sections of code should not be "commented out" using C++ comments [MISRA2008-2_7_3-4]
    • Sections of code shall not be "commented out" using C-style comments [MISRA2008-2_7_2-3]
    • Mod: implement
    • Installed 4 Sep 2009 as LsstDm-5-38 from MISRA2004-2_4
  • 5-41 Minimize use of 'using namespace' when defining symbols
    • Don't write 'namespace usings' in a header file or before an #include [CODSTA-CPP-39 - 3]
    • Mod: secondary rule: 'using' OK only for 'std' library, implement
    • Installed 4 Sep 2009 as LsstDm-5-38; used auto rule generation.
  • 5-42 Handling namespaces when defining symbols
    • -
    • Mod: implement, want uniformity of namespace abbreviation over ALL code

Layout and Comments

Layout

  • 6-1 Multiple statements per line should not be used.
    • Only one statement shall be allowed per line [FORMAT-06-3]
    • Mod: none
    • Installed 4 Sep 2009 as LsstDm-6-1 from FORMAT-06

  • 6-3 Deeply nested code should be avoided.
    • Namespaces will not be nested more than two levels deep [CODSTA-CPP-57-3]
    • Namespaces will not be nested more than two levels deep [JSF-99-3]
    • Avoid deep nesting [METRICS-23-3]
    • Mod: use as template
    • Installed 4 Sep 2009 as LsstDm-6-3 from METRICS-23

  • 6-4 Block layout should be as illustrated in example 1 below (K&R, strongly recommended)
    • Sibling statement lines should be indented to the same level [FORMAT-36-3]
    • First line in control statement body should be indented more than control statement keyword [FORMAT-37-3]
    • Line should be indented by a multiple of four spaces [FORMAT-27-3]
    • NOT: Braces "{}" which enclose a block should be placed in the same column [FORMAT-34-3]
    • Mod: use a template
    • Installed 2 Sep 09 FORMAT-36 unchanged as LsstDm-6-4b - 4
    • Installed 2 Sep 09 FORMAT-37 unchanged as LsstDm-6-4a - 4

  • 6-5 The class declarations should have the following form: ...
    • Order of scopes in class: public before all others [CODSTA-CPP-46-3]
    • Order of scopes in classes: protected before private [CODSTA-CPP-47-3]
    • Mod: implement

  • 6-6 The function declarations should have the following form: ...
    • If a function has no parameters, use ( ) instead of ( void ) [CODSTA-07-3]
    • When declaring functions, the leading parenthesis and the first argument are to be written on the same line as the function name [FORMAT-35-3]
    • 'void' should be used when a function is passed or returns no values [CODSTA-40-3]
    • Mod: use 2 rules to build Lsst rule
    • Installed 4 Sep 2009 as LsstDm-6-6a from CODSTA-07
    • Installed 4 Sep 2009 as LsstDm-6-6b from FORMAT-35
  • 6-7 The 'if-else' class of statements should have the following form:...
    • 'if' and 'else' should be followed by a compound statement [JSF-59_b-2]
    • A project shall not contain unreachable code in 'else' block [MISRA2008-0_1_1_a-3]
    • A project shall not contain unreachable code in 'if/else/while/for' block [MISRA2008-0_1_1_c-3]
    • An if ( condition ) construct shall be followed by a compound statement. The else keyword shall be followed by either a compound statement, or another if statement [MISRA2008-6_4_1-3]
    • All if ... else if constructs shall be terminated with an else clause [MISRA2004-14_10 - 3]
    • Mod: TBD still need MISRA2008-6_4_1
    • Installed 4 Sep 2009 as LsstDm-6-7b from MISRA2004-14_10 unchanged
    • Installed 4 Sep 2009 as LsstDm-6-7a from MISRA2004-14_9 unchanged
  • 6-8 A 'for' statement should have the following form:...
    • The initialization expression in a for loop will perform no actions other than to initialize the value of a single for loop parameter [CODSTA-52-3]
    • The increment expression in a for loop will perform no action other than to change a single loop parameter to the next value for the loop [CODSTA-53-3]
    • A for loop shall contain a single loop-counter which shall not have floating type [CODSTA-CPP-69-3]
    • null initialize or increment expressions in for loops will not be used; a while loop will be used instead [CODSTA-49-3].
    • Mod: implement
    • Installed 4 Sep 2009 as LsstDm-6-8a from CODSTA-52
    • Installed 4 Sep 2009 as LsstDm-6-8b from CODSTA-53-3

  • 6-9 Empty loops should be avoided. But if needed, empty loops must be clearly identified and on a single line:
    • -
    • Mod: implement

  • 6-10 A 'while' statement should have the following form:...
    • The statement forming the body of a 'switch', 'while', 'do...while' or 'for' statement shall be a compound statement [JSF-59_a-2]
    • The statement forming the body of a switch, while, do while or for statement shall be a compound statement [MISRA2008-6_3_1-3]
    • Mod: implement

  • 6-11 A 'do-while' statement should have the following form:...
    • Prefer while statements over do statements [CODSTA-18-5]
    • The statement forming the body of a 'switch', 'while', 'do...while' or 'for' statement shall be a compound statement [JSF-59_a-2]
    • The statement forming the body of a switch, while, do while or for statement shall be a compound statement [MISRA2008-6_3_1-3]
    • Mod:implement

  • 6-12 A 'switch' statement should have the following form: ...
    • An unconditional break statement shall terminate every non-empty switch clause [JSF-193-2]
    • Every switch statement will have at least two cases and a potential default [JSF-196-3]
    • The statement forming the body of a 'switch', 'while', 'do...while' or 'for' statement shall be a compound statement [JSF-59_a-2]
    • A switch statement shall only contain switch labels and switch clauses, and no other code [MISRA2004-15_0_a-3]
    • The final clause of a switch statement shall be the default clause [MISRA2004-15_3-3]
    • The statement forming the body of a switch, while, do while or for statement shall be a compound statement [MISRA2008-6_3_1-3]
    • MISRA2008-6_4_3_a MISRA2008-6_4_3_b MISRA2008-6_4_3_c MISRA2008-6_4_3_d
    • MISRA2008-6_4_3_e MISRA2008-6_4_4 MISRA2008-6_4_5 MISRA2008-6_4_6
    • MISRA2008-6_4_7 MISRA2008-6_4_8
    • Mod: all templates of switch stts

  • 6-13 A 'try-catch' statement should have the following form: ¶..
    • See MISRA2008-15_*_*
    • Mod: implement

  • 6-15 The function return type should be put on the same line as the function name.
    • In a function definition, the return type of the function should be written on a separate line directly above the function name [FORMAT-28-3]
    • Mod: fix

White Space

  • 6-16.a Conventional operators should be surrounded by a space character (except * and /)
    • There shall be a single ASCII space character preceding assignment operators [FORMAT-07-3]
    • There shall be a single ASCII space character following assignment operators [FORMAT-08-3]
    • There shall be a single ASCII space character preceding bitwise operators [FORMAT-09-3]
    • There shall be a single ASCII space character following bitwise operators [FORMAT-10-3]
    • There shall be a single ASCII space character preceding and following logical operators [FORMAT-26-3]
    • Mod:

  • 6-16.b C++ reserved words should be followed by a white space.
    • CODSTA:Avoid internal or external name conflict with a C++ reserved word
    • Reserved identifiers, macros and functions in the standard library, shall not be defined, redefined or undefined [MISRA2004-20_1_a-3]
    • Do not redefine reserved words [MISRA2004-20_1_b-3]
    • Reserved identifiers, macros and functions in the standard library shall not be defined, redefined or undefined [MISRA2008-17_0_1_a-3]
    • Reserved identifiers, macros and functions in the standard library shall not be defined, redefined or undefined [MISRA2008-17_0_1_b-3]
    • There shall be a single ASCII space character following all commas [FORMAT-19-3]
    • Mod: use as template

  • 6-16.c Commas should be followed by a white space.
  • There shall be a single ASCII space character following all commas [FORMAT-19-3]
  • Mod:

  • 6-16.d Colons should be surrounded by white space.
    • There shall be no white spaces surrounding "return" or "sizeof " statements argument or expression [FORMAT-24-3]
    • There shall be a single ASCII space character following all semicolons [FORMAT-20-3]
    • Mod: use as template

  • 6-16.e Semicolons in 'for' statements should be followed by a space character.
    • There shall be a single ASCII space character following all semicolons [FORMAT-20-3]
    • Mod: fix
    • Installed 3 Sep 2009 as LsstDm-6-16e from FORMAT-20 unchanged.

  • 6-18 Logical units within a block should be separated by one blank line.
    • -
    • Mod: NA

  • 6-19 Methods should be separated by one blank line in .h files and two blank lines in .cc files.
    • -
    • Mod: implement

  • 6-20 Variables in declarations should be left aligned where possible.
    • -
    • Mod: implement

  • 6-21.a Use alignment wherever it enhances readability.
    • -
    • Mod: NA

  • 6-21.b Nested namespaces should be aligned left with each level of nesting on a new line.
    • -
    • Mod: implement

Comments

  • 6-22 Tricky code should not be commented but rewritten.
    • -
    • Mod: NA

  • 6-23 All comments must be written in English.
    • -
    • Mod: NA

  • 6-24 Block comments must never be mixed with lines of code.
    • -
    • Mod: NA

  • 6-25 Comments should be included relative to their position in the code.
    • Line should be indented by a multiple of four spaces [FORMAT-27-3]
    • Sibling statement lines should be indented to the same level [FORMAT-36-3]
    • First line in control statement body should be indented more than control statement keyword [FORMAT-37-3]
    • Mod: implement

Legacy Code

  • 7-1 All legacy code should have an interface definition specification that follows these rules.
    • -
    • Mod: NA