1. C++ Programming Style and Rules ¶

Contents

1.1. Introduction ¶

This document outlines the specific rules, applied in the context of the E-ELT ICS SW.

It is needed to define this, since the E-ELT Programming Language Coding Standards (ESO-254539), permit a certain degree of freedom and certain things are not specified in the coding standards.

<https://pdm.eso.org/kronodoc/1100/Get/364180/ESO-254539_1%20E-ELT%20Programming%20Language%20Coding%20Standards.pdf>

As the E-ELT Programming Language Coding Standards is applied as such, this document only contains the non-specified rules of this standard, to be applied for E-ELT ICS SW.

The rules defined in this document, overwrites the rules in the underlying specifications

Remark: It would of course be better if these rules are adopted by the E-ELT Coding Standards.

1.2. General ¶

In addition to E-ELT Programming Language Coding Standards (ESO-254539), the Google C++ Style Guide (GSG) shall be applied.

<https://google.github.io/styleguide/cppguide.html>

Rationale: The ESO SEWG coding standards is based on the ESA C++ standard, which is rather big and complex and thereby more difficult to apply consistently.

1.3. Source Code Formatting ¶

1.3.1. Indentation ¶

4 blank spaces shall be used as indentation.

Rationale: Applying 2 blanks, results in very compact and less readable code.

1.3.2. Declaration of Template Functions/Classes ¶

Template function and classes shall specify the template parameters on a separate line.

Rationale: Makes it easier to determine the type and the signature of the template class or function.

Example:

template<class TYPE>

   void ifw::...(...) {

}

1.3.3. Classes ¶

It is recommended that each class shall be contained in a separate header and C++ source files. Moreover, that a C++ source file does not exceed 2000 lines in size.

Rationale: Having a separate set of source files per class, makes it easier to navigate in the code.It is a general recommendation, not to implement source file, which are too big, making them less manageable.

1.3.4. Template Classes and Functions ¶

Implementation of template classes and functions shall be kept in a separate header.

Rationale: This helps keeping the actual class definition clean of the implementation, making it easier to manage and read.

1.4. Doxygen Documentation ¶

1.4.1. Grouping ¶

Use @name and @{ @} tags to group related items.

Rationale: Makes it clearer in the documentation which logically belongs together.

Example: See <http://www.stack.nl/~dimitri/doxygen/manual/grouping.html>.

The source file templates will provide examples of this and assist in the implementation of this.

1.5. Naming Conventions ¶

1.5.1. Class and struct Member Variable Names ¶

m_<name> shall be used used for non-static member variables.
s_<name> shall be used for static member variables.

Rationale: Makes it easier in the code to distinguish between class variables and automatic variables and input parameters and helps avoiding name clashes.

1.6. Method/Function Signatures ¶

1.6.1. Signature Variables Passed by Reference ¶

The GSG suggest that all parameters passed by reference shall be declared as const. This rule shall not be applied for the ICS. I.e., it shall be possible to assign a value within the method to a variable passed by reference. I.e., output parameters may be non-const whereas pure input parameters shall be const.

Pure input parameters shall be declared as const.

Rationale: Handling variables b y reference, is one of the major improvements of C++ compared to C, where pointers have to be used for this.

Example:

void xxx::yyy::MyClass::locateAndReadFile(const std::string& filename,
                                          std::string& completeFilename,
                                          std::string& fileBuffer) {
   ...
}

1.7. MACROS ¶

The usage of macros should be limited but shall be allowed in cases where appropriate.

Warning

This is violating R-COD-384 of the E-ELT C++ Coding Standards.

1.8. Types ¶

1.9. Type Names ¶

The set of types defined in the context of CII shall be applied. This in particular for the signature of class methods and functions, but should also be used for automatic variables in the code and for class variables.

Note

At this point, it is not clear if CII will provide a set of types and which. In case CII will not provide a set of types, the types defined in /usr/include/c++/<version>/cstdint shall be used.*

E.g. for unsigned short int, int16_t and for long int and long long int, int64_t, shall be used.

Rationale: Helps in generating higher quality code.