#1:
It means, after first including the
main header, all following headers are alphabetical, first "" includes, then <> includes. For header files, the main header is the library main header.
- Code: Select all
#include "../LSGGraphics.h" // Main header. ALL headers in the graphics library FIRST include this file.
#include "Algorithm/LSTLAlgorithm.h" // The rest of the files are alphabetical, starting with "" includes because they are more important than <> includes.
#include "HighLevel/LSFFilesEx.h"
#include "LSGShaderLanguageParser.h"
#include "LSGShaderLexer.h"
#include "LSGShaderParserWrapper.h"
#include "Map/LSTLMap.h"
#include "String/LSTLString.h"
#include "String/LSTLStringList.h"
// One blank line after "" before including <> files.
#include <cassert> // <> includes, again in alphabetical order.
#include <new>
In .CPP files, the
main header is the header that is directly associated with that .CPP file. Typically this is the only #include file in the .CPP, but if there are exceptions, they follow the rules just as well.
#2:
Templated class function definitions must always be in the headers. They are frequently difficult to read regardless of the organization (just try to read debug output from an STL error), and due to the nature of parameterized functions not all environments have decent support for quickly jumping from the declaration to the definition on templated class functions. The one template function I defined in a .CPP file (CStd::FtoA()) Microsoft® Visual Studio® simply cannot find when I right-click its name and jump to its definition.
On top of all of this, templates are very frequently used in cases that require you to overload every single operator there is, and every combination of such operators.
A fixed-point template class requires you to overload every form of mathematical operator (+, -, *, and /), comparison operator (==, !=, >=, >, <=, and <=), and assignment operator (=, +=, -=, *=, and /=), for every basic type (char, short, long, long long, unsigned char, unsigned short, unsigned long, unsigned long long, float, double, AND your fixed-point class), plus casts to and from each of these types, both at class scope and at global scope. Just the overloads I mentioned here add up to 204 functions.
All the while, your IDE is not going to let you easily jump back and forth between the declarations and the definitions because, in Microsoft® Visual Studio® for example, you cannot “Jump to Definition” on operators.
I made the only sane choice. Template classes are always declared and defined at the same time. Since templates are always abstract and hard to read for anyone who did not write them, it doesn’t count against it in the same way that it would a regular class.
#3:
Despite the raw number of people who have asked me to make such a detailed style guide, I remain convinced that it would cause more uproar than anything else.
People won’t get it that it is just one way to go if you haven’t already made your own ways to go.
They will take it as preaching and start whining how stupid one rule is or another or whine that the style is ugly etc.
L. Spiro