1The goal of these guidelines is to allow as much freedom as possible, while keeping the code buildable and pleasant to read.
2
3* Formatting
4
5- Indent with a single tab character. This is the best choice, since anyone can use the visual indentation he prefers by adjust the tab width setting in his editor.
6- Align multiline statements with an additional extra tab before each continuation line
7- Keep in mind that people can program with proportional fonts: hence, don't attempt to align anything not at the start of the line, since it's impossible
8- In general, there should never be two consecutive spaces in the source code
9- There is no strict limit on line length, but try to not make lines too long, and insert a line break where it looks good
10
11* Language/platform features
12
13All language features of C++03 with TR1 and all the STL library may be used.
14Obviously, try to keep the code simple, readable and intuitive, code size small, and compilation time short where possible.
15Platform/compiler-specific extensions can be used if beneficial, protected by #ifs.
16
17C++0x is currently not used since it's unreleased and currently not well supported by clang.
18Once GCC, clang and Visual C++ all have very good or complete support, and ideally the standard is finalized, we can start taking advantage of it.
19Change this document once that happens.
20
21Boost is currently not used because it hasn't been necessary and it's best to keep things simple.
22If really necessary, add a dependency on it, but use it judiciously.
23
24C should be used only for old code, and preferably completely avoided.
25
26You can freely assume that char is 8-bit, short 16-bit and int 32-bit, that long and pointers are 32-bit or 64-bit, that long long is at least 64-bit, that float is 32-bit and that double is 64-bit.
27However, when you intend a specific size, int8_t, etc. are preferred.
28
29* Naming style
30
31 Code implementing public parts of Windows interfaces (and derived ones) should follow Windows naming conventions:
32 - Classes are like GalliumD3D11VertexShader
33 - Functions are like CreateVertexShader
34 - Variables are like ppVertexShader
35
36 Other code should follow Gallium/Linux/POSIX/STL/Boost naming conventions:
37 - Classes are like maybe_mutex_t
38 - Functions are like xs_create_shader
39 - Variables are like sampler_view
40
41 Template parameters are named accordingly to what looks best for the specific case.
42 Typically it will be FooBar for typename parameters and foo_bar for non-typename ones.
43
44 * Implementation style
45
46See the comments in d3d1xstutil.h for the COM implementation method.
47In particular, avoid multiple/virtual inheritance in favor of mixins where possible.
48
49Try to limit or avoid preprocessor magic and multiline macros and use templates instead where possible.
50Often, you can lessen the preprocessor magic by putting some of it in a template instantiated by the remaining magic.
51
52Forward declarations should not be used unless necessary.
53In particular C++ classes should be implemented "inline" and should you should almost never have a forward declaration of a class.
54To achieve this, you can opt to create an "interface class", which goes into an header or earlier in the C++ file, and an "implementation class" with goes in the C++ file.
55Alternatively, use global helpers with forward declaration.
56
57Order definitions so that forward declarations are not necessary (e.g. put main at the end of the file).
58
59Choose between "struct" or "class" depending on whether the first declared member is public or private, to save the explicit specifier.
60
61Try to use const appropriately, esp. as a qualifier for member functions.
62
63Try to avoid Microsoft-style TYPES like FLOAT, UINT, etc. in favor of the usual C types like float, unsigned.
64
65Where feasible, if a platform is missing a function/keyword, add a definition of it with the standard name, rather than inventing an "abstraction layer".
66
67Try to use typedefs for STL maps on which  you need to declare iterations, as well as function pointers or other "weird" C types.
68
69 To iterate, use the following idiom from LLVM, which is optimal, unless end() is trivial:
70 for(iterator_type i = begin(), e = end(); i != e; ++i)
71 {}
72
73 Otherwise, you risk the compiler evaluating end() for each loop iteration.
74 If end() is trivial, use this:
75 for(iterator_type i = begin(); i != end(); ++i)
76 {}
77
78 Note the "++i" instead of the "i++" to avoid creating an unnecessary copy (esp. with overloaded operators).
79
80 Declare variables just before they are  needed, and inside the for() header.
81 Usually, you should initialize variable in the declaration if that's the only assignment or if it is a default value, and as a separate assignment if not.
82
83Try to use C++ references (with const if appropriate) when the pointer must be non-null, and that type is not already customarily passed with a pointer.
84
85