Description of the coding style used in MeteoIO Other:howto
The recommended coding style for MeteoIO is the Kernel coding style with a few exceptions:
- we don't enforce strict 80 characters line width. try to remain reasonable, but don't necessarily cut everything off at 80 characters
- try to intelligently use spaces to visually group elements of a complex formula. If the formula can be split into meaningful elements, please do it (using some "const double element = " constructs).
- try to properly qualify variables: for example, if a variable will not be changed, will never be negative and always integer, then use "const unsigned int". When some specific types are used for some standard library calls, try to properly use these types (for example, "size_t")
- use C++ method naming convention: a method name starts with lowercase letter and each individual word in a name starts capitalized. Usually, no underscores are used in a method. For example, a method that would return the lapse rate contained in an object would be named "getLapseRate()"
- qualify variables and parameters with "const" when appropriate (see const-keyword).
A few important points to emphasize (from the Kernel coding style):
- Functions should be short and sweet, and do just one thing. They should fit on one or two screens of text, and do one thing and do that well.
- If you have a complex function, and you suspect that a less-than-gifted first-year high-school student might not even understand what the function is all about, you should adhere to the maximum limits all the more closely. Use helper functions with descriptive names.
- Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it's much better to write the code so that the working is obvious, and it's a waste of time to explain badly written code.
Since every user has his/her own preference for the ideal indentation width, please use "smart tabs". That practically means:
- indent with tabs
- align with spaces
This way, each developer can set his/her indentation size as he/she wishes without forcing his/her choice to others...
Memory management and Containers
Please do NOT manage memory manually but use Standard Template Library (STL) containers instead. This dramatically reduces memory errors (ie: segfaults), often offers more performance and provides you with lots of associated algorithms (like sorting, search, filling, etc).
When you need your own data class, please design it based on these STL containers (like grid2DObject is based on std::vector).
Basically, this means that you will replace mallocs and arrays by vectors (for 1d, 2d, 3d grids), maps (for multiple key/value pairs), lists (for unordered table), etc
The recommended C++ usage should be followed: "throw by value, catch by reference" (as specified in C++ Coding Standards: 101 Rules, Guidelines, and Best Practices, Herb Sutter, Andrei Alexandrescu, 2004, Addison-Wesley Professional). Moreover, we should consider catching by const reference and not even declaring a variable if not doing anything with it: something like
catch(const IOException&) would often be enough.
When compiling in debug mode, lots of warnings are enabled. This should be seen as valuable tips, not as an hindrance. But please fix every single warning before committing your code. Please also address the root cause of the warning, do not simply silent it: for example a warning about potentially uninitialized variable is not fixed by setting the variable to zero when declaring it, but by looking at how the variable might get used before being initialized to a proper value (it could be that the variable is only required in a more limited scope, that some cases have been forgotten, etc) and modifying the code and/or code structure in a way that fixes it.
Only in very rare cases a warning will be tolerated (or silenced), for example when using a long long (which is supported by the newest version of c++ but we don't want to turn all older compilers off when they usually support long long as a compiler extension).