wiki:CodingStandardsRequired
Last modified 10 years ago Last modified on 12/22/2009 05:49:09 PM

from DRAFT LSST C++ Coding Standards: Required Rules

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

Introduction

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

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

General Recommendations

  • No required rules stated.

Naming Conventions

General Naming Conventions

  • 3-1 Names of user defined types must be in mixed case starting with uppercase
    • Class, struct, union, enum, and typedef names are to start with an uppercase letter [NAMING-10-3]
    • Mods:
    • Installed 25 Aug 2009 as LsstDm-3-1; unchanged from NAMING-10
  • 3.2 Variable names must be in mixed case starting with lower case.
    • Begin local variable names with a lowercase letters [NAMING-05-3]
    • Begin global variable names with a lowercase letters [NAMING-06-3]
    • Begin member variable names with a lowercase letters [NAMING-07-3]
    • Mods:
    • Installed 27 Aug 2009 as LsstDm-3-2a unchanged from NAMING-5
      • Modified 2 Dec 2009 to handle both local and global/boolean and non-boolean variables.
    • Installed 27 Aug 2009 as LsstDm-3-2b unchanged from NAMING-6
    • Installed 27 Aug 2009 as LsstDm-3-2c unchanged from NAMING-7

  • 3-3 Named constants (including enumeration values) must be all uppercase using underscore to separate words.
    • Identifiers for constant and enumerator values shall be lowercase [NAMING-42-2]
    • Mods: change to all uppercase
    • Installed 25 Aug 2009 as LsstDm-3-3; modified NAMING-42-2 to require uppercase, underscore allowed within identifiers.
  • 3-4 Names representing methods or fuctions should be verbs and must be written in mixed case starting with lowercase. Do not put a space between the function name and the opening parenthesis when declaring or invoking the function.
    • Global function names should start with lowercase [NAMING-34-3]
    • Member function names should start with lowercase [NAMING-35-3]
    • Place left parenthesis directly after function name [FORMAT-30]
    • Installed 3 Sep 2009 as LsstDm?-3-4a from NAMING-34; no change
    • Installed 3 Sep 2009 as LsstDm?-3-4b from NAMING-35; no change
    • Installed 9 Oct 2009 as LsstDm?-3-4c from FORMAT-30; no change
  • 3-5 A name representing a typedef must be initial letter capitalized, camel-case with no prefix of the enclosing class and no suffix of 'T' or 'Type'.
    • Begin class, struct, union, enum, and typedef names with an uppercase letter [NAMING-09-3]
    • Append names of non-scalar typedefs with '_t' [Naming-29 - 3]
    • Do not use identifiers which begin with one or two underscores (_' or ') [NAMING-33-3] (Note: need to fix version used in other LsstDM rule)
    • Number of private data member(s) per class [METRICS-09-3]
    • Mods: add in "_type", "_T", "_Type" also;
    • Mods: STILL NEED ENCLOSING CLASS PREFIX RESTRICTION
    • Installed 27 Aug 2009 as LsstDm-3-5a; modified NAMING-29-3 to inhibit "_t", "_type", "_T", "_Type"
  • 3-6 Names representing namespaces should be all lowercase and based on component or directory name.
    • Only the first word of the name of a class, structure, namespace, enumeration, or typedef will begin with an uppercase letter [NAMING-40-3]
    • Mod: remove superfluous requirements
    • Installed 3 Sep 2009 as LsstDm-3-6a; used NAMING-40-3 as template.

  • 3-8 Abbreviations and acronyms must not be uppercase when used as name.
    • Mods: implement
  • 3-9 Global variables should be avoided and if used always be referred to using the "::" operator. (Also in desirable)
    • Whenever a global function is referenced, use the :: operator [CODSTA-CPP-23-5]
    • Mods: none
    • Installed 25 Aug 2009 as LsstDm-3-9; unchanged from CODSTA-CPP-23
  • 3.10 Private class variables must have underscore prefix.
    • Do not use identifiers which begin with one or two underscores [Naming-33 - 3]
    • Eliminate unused private member variables [OPT-05-3] (modified)
    • Mods: implement

  • 3-12 All names must be written in English and use American English spelling.
    • Mods: no implementation

Specific Naming Conventions

  • 3-15 The terms 'get/set' must be used where an attribute is accessed directly and in the imperative form. The variable name portion should be the same as the actual variable name but now with the first letter capitalized.
    • Mods: implement
  • 3-25 Complement names must be used for complement operations.
    • Always close transactions [BD-MISC-TRANS-1]
    • Mods: This Rule works but needs 'parameterization' i.e. lots of hand-tuning identifying complementary names.
  • 3-28 Negated boolean variable names must be avoided.
    • Mods: implement

Files

Source Files

  • 4-1 C++ header files must have the extension .h (preferred) or .hpp (allowed). Source files must have the extension .cc.
    • Header files will always have a file name extension of ".h" [NAMING-41-3]
    • Implementation files in C++ always have the file name extension ".cc" [NAMING-38-3]
    • Mods: add option .hpp extension
    • Installed 25 Aug 2009 for .cc as LsstDm-4-1a (note no '-' before 'a') from NAMING-38
    • Installed 25 Aug 2009 fo .h | .hpp as LsstDm-4-1b (note no '-' before 'b') from NAMING-41
  • 4-1.a The head of each .h and each .cc must begin with a fixed format comment declaring the file contents and format to emacs.
    • Comment every file [COMMENT-03-3]
    • Provide copyright information [COMMENT-02-3]
    • Mods: Add comment contents requirements
  • 4-4.b All templatized classes/functions shall be explicitly instantiated, i.e. the type declared and the instances to be used explicitly in the header file, the type members are defined in the source file.
    • A copy constructor shall be declared when there is a template constructor with a single parameter that is a generic parameter [MISRA2008-14_5_2-3] (This probably belongs elsewhere)
    • MISRA2008:A copy assignment operator shall be declared when there is a template assignment operator with a parameter that is a generic parameter [MISRA2008-14_5_3-3](This probably belongs elsewhere)
    • All partial and explicit specializations for a template shall be declared in the same file as the declaration of their primary template [MISRA2008-14_7_3-3]
    • NOTE: Review all the Parasoft template rules.
    • Mods: implement
  • 4-5 Inline functions are prohibited except for simple accessors/mutators that get or set a simple attribute.
    • Do not define inline functions in source files [CODSTA-CPP-51-3]
    • Avoid inline constructors and destructors [OPT-17-3]
    • Only functions with 1 or 2 statements should be considered candidates for inline functions [OPT-25-4]
    • Member function containing recursion or loops should not be inlined [OPT-18-3]
    • NEGATIVE: Trivial accessor and mutator functions should be inlined [OPT-23-4]
    • NEGATIVE: Trivial forwarding functions should be inlined [OPT-24-4]
    • Mods: needs some work...
    • Installed 25 Aug 2009 LsstDm-4-51 unchanged from OPT-17
  • 4-6 File content must be kept within 110 columns.
    • Source lines will be kept to a length of 120 characters or less [METRICS-26-3]
    • Source lines will be kept to a length of 120 characters or less [JSF-41-3]
    • Mods: fix width max
    • Installed 25 Aug 2009 as LsstDm-4-6 from JSF-41-3 and modified to fix line length to 110 chars.
  • 4-8 The incompleteness of split lines must be made obvious.
    • 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]
    • When declaring functions with more than 2 parameters, the leading parenthesis and the first argument are to be written on the same line as the function name, each additional argument will be written on a separate line [FORMAT-38-3]
    • Mods: needs work

Include Files and Include Statements

  • 4-9 Header files must include a construction that prevents multiple inclusion.
    • Use multiple include guards [PFO-02-3]
    • Precautions shall be taken in order to prevent the contents of a header file being included twice [MISRA2004-19_15-3]
    • Mods:
    • Installed 26 Aug 2009 LsstDm-4-9 from PFO-02
  • 4-11 Include statements must be located at the top of a file only.
    • #include statements in a file should only be preceded by other preprocessor directives or comments [MISRA2004-19_1-3]
    • Mods:
    • Installed 26 Aug 2009 LsstDm-4-11 from MISRA2004-19_1
  • 4-12 There must be no unused include files listed in the source.
    • Mods: NA
  • 4-13 Using declarations and using directives must not be used in header files.
    • Don't write namespace usings in a header file or before an #include [CODSTA-CPP-39-3]
    • There shall be no unnamed namespaces in header files [MISRA2008-7_3_3-3]
    • Mods: second clause may be removed.
    • Installed 26 Aug 2009 LsstDm-4-13 from CODSTA-CPP-39

Statements

Types

  • 5-2 The parts of a class must be sorted 'public','protected', and 'private'.
    • 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]
    • Mods:
    • Installed 26 Aug 2009 LsstDm-5-2a from CODSTA-CPP-46
    • Installed 26 Aug 2009 LsstDm-5-2b from CODSTA-CPP-47
  • 5-3 Avoid type conversions as far as possible. When required type conversion must always be done explcitly using C++ style casts. (Also Desirable)
    • Prefer C++-style casts [CODSTA-CPP-11-3]
    • Implicit conversions which may result in a loss of information shall not be used [MISRA-043-3]
    • Mods:
    • Installed 26 Aug 2009 LsstDm-5-3 from CODSTA-CPP-11

Variables

  • 5-6 Variables must never have dual meaning.
    • Mods: NA
  • 5-8 Non-constant and instance variable must be declared private.
    • Mods: implement

Loops

  • 5-14 Only loop control statements must be included in the 'for()' construction.
    • Do not declare variables in "if", "for", "while", and "do while" statement [OPT-10-3]
    • The three expressions of a for statement shall be concerned only with loop control [MISRA2004-13_5-3]
    • Mods:
    • Installed 26 Aug 2009 LsstDm-5-14 from MISRA2004-13_5

Conditionals

  • 5-22 Executable statements in conditionals must be avoided.
    • Assignment operators shall not be used in expressions that yield a Boolean value [JSF-160-2]
    • Assignment operators shall not be used in expressions that yield a Boolean value [MISRA2004-13_1-3]
    • Mods:
    • Installed 26 Aug 2009 LsstDm-5-22 from MISRA2004-13_1

Methods/Functions?

  • 5-23 Functions must always have the return value explicitly listed.
    • Whenever a function is declared or defined, its type shall be explicitly stated [MISRA2004-8_2_a-3]
    • Mods:
    • Installed 26 Aug 2009 LsstDm-5-23 from MISRA2004-8_2_a
  • 5-25 Class methods that do not update internal data nor return references/pointers to internal data must use the 'const' label at the end of the signature.
    • Member functions shall be declared const whenever possible [CODSTA-CPP-54-3]
    • Mods:
    • Installed 26 Aug 2009 LsstDm-5-25 from CODSTA-CPP-54-3
  • 5-26 All methods that return references/pointers to internal data must provide both a constant and non-constant version when appropriate.
    • const member functions shall not return non-const pointers or references to class-data [MISRA2008-9_3_1-3]
    • Member functions shall not return non-const handles to class-data [MISRA2008-9_3_2-3]
    • Avoid member functions that return pointers or references to members less accessible than themselves [OOP-12-3]
    • A public member function must never return a non-const reference or pointer to member data [OOP-36-3]
    • Return value of a function must match declared return type [PB-05-3]
    • A function shall not return a reference or a pointer to a parameter that is passed by reference or const reference [PB-39-3]
    • A function shall not return a reference or a pointer to an automatic variable (including parameters), defined within the function [PB-40-3]
    • Mods: implement

Constructors and Destructors

  • 5-27 Constructors taking one argument must be declared as 'explicit'.
    • Constructors allowing for conversion should be made explicit [CODSTA-CPP-04-1]
    • All classes should contain the copy constructor [MRM-05-3]
    • Mods: both needed due to secondary requirement in 5-27
    • Installed 26 Aug 2009 LsstDm-5-27a from CODSTA-CPP-04
    • Installed 26 Aug 2009 LsstDm-5-27b from MRM-05-3
  • 5-28 Destructors must not throw exceptions.
    • Never allow an exception to be thrown from a destructor, deallocation, and swap [EXCEPT-01-1]
    • Do not throw from within destructor [EXCEPT-03-1]
    • A class destructor shall not exit with an exception [MISRA2008-15_5_1-3]
    • Mods:

Miscellaneous

  • 5-36 Exceptions must not be declared in method signatures, and all exceptions must be documented with the '@throw' tag.
    • Where a function's declaration includes an exception-specification, the function shall only be capable of throwing exceptions of the indicated type(s) [MISRA2008-15_5_2-3]
    • Where a function's declaration includes an exception-specification, the function shall only be capable of throwing exceptions of the indicated type(s) [EXCEPT-14-3]
    • Mods: needs work
  • 5-39 Use the 'std::String' class rather than 'char *'
    • Consider using vector<char> instead of string [STL-11-4]
  • Mods: consider as template
  • 5-40 Use 'std::vector<Foo>' over array declaration (e.g. Foo[]).
    • Use vector and string instead of arrays [STL-37-3]
    • Prefer vector and string to dynamically allocated arrays [STL-10-3]
    • Mods: needs work
    • Installed 25 Aug 2009 as LsstDm-5-40; copied from STL-10

Layouts and Comments

Layout

  • 6-2 Basic indention must be 4 spaces
    • Line should be indented by a multiple of four spaces [FORMAT-27-3]
    • Mods:
    • Installed 25 Aug 2009 as LsstDm-6-2; copied from FORMAT-27
  • 6-14 Single statement 'if-else' , 'for' or 'while' statements must only be written without brackets if on one line.
    • The statement forming the body of a 'switch', 'while', 'do...while' or 'for' statement shall be a compound statement [MISRA2004-14_8-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]
    • The statement forming the body of a 'switch', 'while', 'do...while' or 'for' statement shall be a compound statement [JSF-59_a-2]
    • Mods: use as template

White Space

Comments

  • 6-23 All comments must be written in English.
    • Mods: NA
  • 6-24 Block comments must never be mixed with lines of code. *
    • Mods: NA

Legacy Code

BUGS in Current Rule Implementation

LsstDm 3-9

On Thu, Oct 01, 2009 at 01:51:28PM -0700, Kian-Tat Lim wrote:

>
> > /utils/src/Utils.cc
> >    36:  Whenever a global function is referenced, use the :: operator
> >         LsstDm-3-9-3
>
> The line in question is:
>
> >     if (boost::regex_search(headURL, matchObject, getURL)) {
>
> This appears to me to be properly qualified with a namespace using the
> "::" operator.  Adding an additional "::" would be incorrect.
>

Fixed 2 Oct 2009 so that <<namespace>>::function() does not trip this infraction.

LsstDm 3-2a

The Rules for

  • variables (lsst 3.2a Variable names must be in mixed case starting with lower case.) and
  • constant variables (Lsst 3.3 Named constants (including enumeration values) must be all uppercase using underscore to separate words.)

are conflicted for Statistics.cc: line 25

I will edit Rule 3.2a to ensure it checks that the variable is not declare const.

Fixed 2 Oct 2009.

LsstDm 6-2

In afw/src/math/Statistics.cc line 41:

Incorrect error in LsstDm?-6-2 "Line should start at first column "

math::Statistics::Statistics(Image const &img, ///< Image whose properties we want
                             Mask const &msk,   ///< Mask to control which pixels are included
                             int const flags, ///< Describe what we want to calculate
                             StatisticsControl const& sctrl ///< Control how things are calculated
                            ) : _flags(flags),
                                _mean(NaN), _variance(NaN), _min(NaN), _max(NaN), _sum(NaN),
                                _meanclip(NaN), _varianceclip(NaN), _median(NaN), _iqrange(NaN),
                                _sctrl(sctrl) {