C/C++ Programming Rules
Total Page:16
File Type:pdf, Size:1020Kb
C/C++ Programming Rules DRAFT DRAFT C/C++ programming rules Technical Reference Manual DRAFT Version: 1.0 SVN Revision: 52580 June 21, 2018 C/C++ programming rules, Technical Reference Manual Published and printed by: Deltares telephone: +31 88 335 82 73 Boussinesqweg 1 fax: +31 88 335 85 82 2629 HV Delft e-mail: [email protected] P.O. 177 www: https://www.deltares.nl 2600 MH Delft The Netherlands DRAFT For sales contact: For support contact: telephone: +31 88 335 81 88 telephone: +31 88 335 81 00 fax: +31 88 335 81 11 fax: +31 88 335 81 11 e-mail: [email protected] e-mail: [email protected] www: https://www.deltares.nl/software www: https://www.deltares.nl/software Copyright © 2018 Deltares All rights reserved. No part of this document may be reproduced in any form by print, photo print, photo copy, microfilm or any other means, without written permission from the publisher: Deltares. Title C/C++ programming rules Client Project Reference Pages Deltares 11200568 - 54 Classification public Keywords C/C++ Summary C/C++ programming rules are defined to guarantee the reliability and stability of a modelling suite. The aim of these C/C++ Programming rules is to meet future demands of users with respect to functionality, flexibility, accessibility, modularity and performance. References - Version Date Author Initials Review Initials Approval Initials 0.01 2005 Arjen Markus Jan Mooiman Arthur Baart 1.00 28 Sep 2017 Arjen Markus Jan Mooiman Joost Icke DRAFT Status final Deltares iii C/C++ programming rules, Technical Reference Manual DRAFT iv Deltares Contents Contents 1 Declarations 1 1.1 Variables...................................1 1.2 Global (external) variables..........................1 1.3 Constants...................................2 1.4 Type variables................................3 1.5 Macros....................................3 1.6 Prototypes..................................4 1.7 Pointer prefix.................................4 2 Control statements5 2.1 General....................................5 2.2 Loop constructs................................5 2.3 Selections via switch/case..........................8 2.4 Conditional statements............................9 2.5 Subroutines and functions.......................... 10 2.6 Error handling................................. 11 2.7 Using the C preprocessor........................... 12 3 Using I/O 15 3.1 Opening and closing files........................... 15 3.2 Standard input and output........................... 15 3.3 Reading and writing.............................. 15 4 Expressions and assignments 19 4.1 Varargs.................................... 19 4.2 True and false................................. 19 4.3 Parentheses................................. 19 4.4 Implicit assignments............................. 20 4.5 Conditional expressions............................ 20 4.6 Loop conditions................................ 21 4.7 Token pasting................................. 21 4.8 Debug statements.............................. 21 4.9 General................................... 21 4.10 Errors and functions............................. 22 4.11 Pointers and functions............................ 22 4.12 Type casting................................. 22 4.13 NULL pointers................................ 23 5 File organisation 25 5.1 Source files.................................. 25 5.2 Include files.................................DRAFT 26 6 Layout, internal documentation 29 6.1 Naming conventions............................. 29 6.2 Language.................................. 29 6.3 Order of program text parts.......................... 29 6.4 Comment................................... 30 6.5 Alignment of declarations........................... 31 6.6 Statements.................................. 31 6.7 Assignments and expressions......................... 31 6.8 Letters.................................... 31 6.9 Line length.................................. 31 6.10 File length.................................. 32 Deltares v C/C++ programming rules, Technical Reference Manual 6.11 Function length................................ 32 6.12 Spaces.................................... 32 6.13 Braces.................................... 32 6.14 Indentation.................................. 33 6.15 Empty lines.................................. 33 6.16 Fileheader.................................. 33 6.17 Function header............................... 33 6.18 Functions and parameters.......................... 34 6.19 Variable/constant............................... 34 6.20 Version information.............................. 35 7 Recommendations 37 7.1 Source and include files............................ 37 7.2 Names of routines and functions....................... 38 8 Prohibited statements and constructions 41 8.1 Forbidden data types............................. 41 8.2 Null statement................................ 41 8.3 Forbidden standard functions......................... 41 8.4 Illegal use of pre-processor constructs.................... 41 8.5 Illegal use of functions............................ 43 References 45 A Set/get functions 47 B Examples 49 B.1 Example C module (.c)............................ 49 B.2 Example C header file (.h).......................... 51 DRAFT vi Deltares 1 Declarations 1.1 Variables Each variable must be declared on a separate line. Each variable must be explained by means of a comment string. This comment string will be placed directly after the declaration or definition and may be continued on one new line at the most. Local variables must be declared at the beginning of a function and also at the beginning of a block. All basic variables (int, float, char, long, short and double) are initialised at declaration. Don’t assume the compiler will initialise variables at zero or blanks for you. Exceptions to this rule are static and external variables, according to ANSI C they will always be initialised at zero. Mind the usage of already defined functions. Examples: Compliant Not compliant long lower = 0; /* Lower bound */ int lower, upper, step; long upper = 300; /* Upper bound */ float eps; long step = 20; /* Step size */ char c; float eps = 1.0e-5; /* Smallest difference */ char c = ’\\’; /* Escape char */ 1.2 Global (external) variables Global variables are inevitable from time to time: It may be necessary to keep the state of the program in a globally available structure, because in most user-interfaces the callback functions that are typically used to handle window events do not allow an arbitrary argument list. It may be necessary to pass information on to higher-level routines, for instance error conditions and there is no way (because of third-party libraries) to handle this information flow via an argument that is passed by reference. When using such tools as Yacc and Lex, information is mainly transferred via global vari- ables, as there is no other way. Therefore we need an etiquette for the use of global variables. This etiquette is given below: The use of global variablesDRAFT is forbidden (with or without the static attribute), unless they are contained in a structure. The definition of this structure is contained in an include file as a separate user-defined type (typedef). Any routine seeking to use this globally available structure, should obtain a pointer to this structure either via its argument list or via a function call: In the include file: /* Definition of the program state */ typedef struct _ProgramState { ... Deltares 1 of 54 C/C++ programming rules, Technical Reference Manual } ProgramState, *ProgramStatePtr; /* Auxiliary function - obtain the program state */ ProgramStatePtr *GetProgramState(void); In some routine: long routine( ... , ProgramStatePtr statep, ... ) { ... /* Update the program state */ ... } Or alternatively: long routine( ... ) { ProgramStatePtr statep; statep = GetProgramState(); /* Update the program state */ ... } The global variables within this structure can best be updated via get/set routines, rather than direct assignments to the individual fields, as this makes the application less susceptible to changes in the structure. One advantage of using structures and pointers to these structures is that, should it become necessary to distinguish several such items, one can simply allocate a new structure of this type and fill it. 1.3 Constants The best way to define constants is to declare them with the const qualifier. This way you specify that its value will not be changed. Using the const qualifier for an array it says that the elements will not be altered of when used for array arguments it indicates that the function does not change that array. An advantage is the compiler checking of the variables that have been declared with the const qualifier.DRAFT Examples: const long number = 42; /* Crucial number */ const double e = 2.71828182845905; /* Math’s exp(1) */ const char msg [ ] = "warning~: "; /* Prefix for messages */ long KeyValue( const char [ ] ); 2 of 54 Deltares Declarations 1.4 Type variables Types play an important role in C programming. C provides a facility called typedef for creating new data type names, to be used as more explanatory synonyms. Especially use typedef for multi-dimensional arrays, pointers to functions or pointers to user-defined structures. Caution The scope of some basic C-types is platform dependent or even compiler dependent. For that reason porting an information system from one platform to another may cause adjustments to that information system. This is hardly avoidable in those cases