513 Service Part Appendix : A Style Guide for Geodetic Software in C and C++ – 514 References – 524 Index – 531 © Springer International Publishing Switzerland 2017 A.N.J. Neidhardt, Applied Computer Science for GGOS Observatories, Springer Textbooks in Earth Sciences, Geography and Environment, DOI 10.1007/978-3-319-40139-3 514 Appendix: A Style Guide for Geodetic Software in C and C++ Appendix: A Style Guide for Geodetic Software in C and C++ Main Topics in This Chapter 7 Sect. 2.7.1. Not all the directories suggested are manda- The following chapter contains a reduced selection of tory. If they contain no files, they can be left out and cre- important and helpful rules, mostly taken from the style ated when needed. guide and programming policies which are used at the Geodetic Observatory Wettzell. The following zz Rule 2: File Names and Internal File Structure suggestions do not claim to be complete, but are a collection of hints, tricks, and definitions, which simplify Languages Relevance the common development of software in a team. The C/C++ + chapter is split into sections about: 55 General structures 55 Preprocessor directives 55 Plain coding Code files are collections of function sets with the same pur- 55 Functions and methods pose or characteristics. File names should be descriptive. For 55 Libraries portability, the names are lower case, but can contain «_» as separation between the logical word parts. Files with pure C code have the extension «.c» for the source file and «.h» for the header file. In the same way C++ code uses the extensions A.1 Introduction «.cpp» and «.hpp». A source/header-tuple defines a module or component. There is a strict separation between the declara- The following sections describe the most useful or critical tions (function/method head) as interface to the module in the rules based on experience at the Wettzell observatory, and header file and the definitions (body with functional code) in which are collected in the local design rules definitions (see the source file. A source file with its related header file is a soft- (Dassing et al. 2008)). The following rules make no claim to ware module. There is only one exception to this strict separa- be complete, but are a minimal set of guidelines which help tion: templates. The function body of template functions must to write better code. be located in the header file because of the language syntax. Relations between modules are organized using the related header files in precompiler include directives. External variables A.2 General Structures and functions (defined with the tag extern« ») are not allowed. The internal structure is a sequence of (see also . Fig. A.1): 55 Comment header (version control tags, general info, zz Rule 1: Project Structure interface info, authors, etc.) (see 7 Sect. 2.5.1 and 7 Sect. 2.7.2) Languages Relevance 55 Define or include guard «begin» directive (only in the header files, see 7 Sect. 2.3.2) C/C++ + 55 Preprocessor directives in a particular order (should be used only in reduced form in header files to keep includes local): Software is developed within a project to do a specific 55All «define» statements set of tasks. For this reason, it helps to create a suitable 55All «include» statements for standard libraries in the directory tree for each project, as this can also be used for standard library path (such as <stdio.h> (with a repository in a version control system (see 7 Sect. 2.7.). extension «.h») for C code libraries (Kernighan and It makes sense to organize the directories hierarchically. Ritchie 1990, l.c. page 86) or <string> (without The first level of this hierarchy represents the repository extension) for C++ code libraries) view (Wassermann 2006, l.c. page 47). The next level of the 55All «include» statements for modules in the local tree contains a general view of the project and can be sepa- work path (identified with quotes) (Kernighan and rated into directories and subdirectories, as shown in Ritchie 1990, l.c. page 86) 515 Appendix: A Style Guide for Geodetic Software in C and C++ .. Fig. A.1 The structure of a software module with a header Software module and a source code file CommentComment header header: Comment header: - Version control info - Version control info - Description - Description “define”/include guard begin Preprocessor directives: - Defines Preprocessor directives: - Includes of standard libraries - Defines - Includes of local modules D - Includes of standard libraries - Includes of local modules Definition of function/method (function body) Declaration of function/method Declaration of function/method Definition of function/method (function body) Declaration of function/method ... ... “define”/include guard end Comment trailer Comment trailer Header file (.h/.hpp) Source file (.c/.cpp) 55 Sections with logically combined declarations (in header In general, a class can be related to a specific module. files) or definitions (in source files) of functionalities1 of The class itself contains member elements like attributes the same characteristics (variables) and methods (functions). The class structure 55 Define or include guard «end» directive (only in the is ordered from the highest restricted parts (which are header files) only accessible within the class object and defined with 55 Comment trailer (see 7 Sect. 2.7.2) the keyword «private»), followed by the inheritable parts (which are accessible within the class object, from A very important instrument in header files to avoid multiple all derived class objects, and defined with the keyword includes, and therefore multiple declarations, is the include «protected») and the public interface parts (which are guard (see 7 Sect. 2.3.2). accessible from outside as interface methods to the class Additionally, line length is normally standardized by style functionality, and are defined with the keyword guides, which help to print the code properly onto standard «public­ ») as shown in . Fig. A.2. The use of «friend» paper sizes. Normally, large code projects are no longer printed. methods or classes should be avoided to keep clear access Therefore, this rule is not as important as it was. Nevertheless, structures. Each restriction block should be ordered as it is quite helpful to standardize on a normal print-width (about well. The first section defines constants and enumera- 80 characters), as it makes the code more readable. tions, followed by internal new data types defined by class descriptions such as for exceptions. The next section zz Rule 3: Class Structure and Obligatory Members defines member variables followed by class methods. Each class must have the standard constructor (which is Languages Relevance called each time an object of this class is created without C++ ++ specific definitions), a copy constructor­ (used to create a new object containing the values from an existing one), the destructor (called each time an object is destroyed, for example, at the end of a local scope), and the copy 1 Functionalities are called «functions» in C and «methods» in C++, ­assignment operator (operator =, which is used to assign as they describe the behavior of a class. the content of an existing object to another existing 516 Appendix: A Style Guide for Geodetic Software in C and C++ zz Rule 4: Naming Conventions class <name> { Languages Relevance PRIVATE Constants/enumerations C/C++ +++ Member classes/exceptions Member variables Methods/functions Even though naming is quite arbitrary, it is useful to PROTECTED Constants/enumerations define some conventions. Names should directly provide Member classes/exceptions information about the characteristics of a named element. It Member variables Methods/functions should directly be visible whether it is a new defined type, a function, or a variable, and the name should make clear PUBLIC Constants/enumerations which type of variable it is, or even what the return value of a Member classes/exceptions function is. Combinations of variables such as arrays or Member variables higher sophisticated class types should also be derivable from Methods/functions the name. An early definition to support such ideas was given - Constructors - Destructors by the Hungarian Notation of Charles Simonyi (Maguire - Overloaded operators 1993, l.c. page xxv–xxviii). As this notation helps to visually - (Other) methods/functions identify, for example, type mismatches in the code, a similar definition which also includes C++ elements is effective. The following notation is a step-by-step extended heading char- }; acter set in front of a descriptive identifier. It offers more details (as type or structure) and classifies the named identi- .. Fig. A.2 The structure of a class in a software module fier in the following way for variables and functions: object). As these functions are called implicitly, for 4. Notation Prefix: memory class ­example, if the new class objects are used within lists or + 3. Notation Prefix: access maps, they are essential. If one of the functions or opera- + 2. Notation Prefix: combination tions is not allowed in the context of a specific class, the + 1. Notation Prefix: type individual function must be blocked by defining it as + Descriptive identifier name private. and in the following way for new type definitions: Descriptive type name kExample A.1 + Notation Postfix: constitution Obligatory member functions The identifier and type names themselves should be class callisto_dewar descriptive and should avoid acronyms. Variable names and { type names are a combination of nouns (e.g., «MinIndex» private: or «IndexCounter»). Function names should be an // ... imperative combination of nouns and verbs which describe public: the activity done within the function body (e.g., // General class functions « » or « »). The logical // Constructor GetFamilyName SumIntegers callisto_dewar (); patterns in the names are separated by capital letters (e.g., // Copy-constructor «CalculateMeanElevation»). Together with the callisto_dewar (const callisto_ type codings from the notation, the name follows the dewar & CIn); «camel case» style (e.g., «uiArrayIndex»).