Debian Codegraph @

storage/maria/libmarias3/docs/contributors/coding_standards.rst

raw
1 Coding Standard
2 ===============
3
4 General
5 -------
6
7 We are aiming for a minimum of C99 support. A script in ``extra`` can be found called ``astyle.sh``. This uses the Linux tool `Artistic Style <http://astyle.sourceforge.net/>`_ to enforce coding standards.
8
9 Coding Style
10 ------------
11
12 Everyone has a preferred coding style, there is no real correct style. What is important is that we stick to one style throughout the code.
13
14 We should use a variant of the `Allman coding style <http://en.wikipedia.org/wiki/Indent_style#Allman_style>`_. The variation is to use 2 spaces instead of tabs. The exception to the rule is Makefiles where space indentation can break them.
15
16 Allman style specifies that braces associated with a statement should be on the following line with the same indentation and the statements inside the braces are next level indented. The closing braces are also on a new line at the same indentation as the original statement.
17
18 For example:
19
20 .. code-block:: cpp
21
22 while (x == y)
23 {
24 something();
25 somethingelse();
26 }
27 finalthing();
28
29
30 Types
31 -----
32
33 Use C99 types (where possible), this will very much help us to find conversion bugs. So:
34
35 * Use bool, not my_bool.
36 * Use true and false, not TRUE and FALSE (those macros need to die).
37 * ulong → uint32_t
38 * ulonglong uint64_t
39 * long int → int32_t
40
41 The keyword :c:type:`NULL` should always be used when referring to the pointer NULL
42
43 Allocation
44 ----------
45
46 For performance reasons we should try to limit the number of times we allocate and deallocate memory. Do not do thousands of allocates and deallocates to save 32k of RAM.
47
48 Naming style
49 ------------
50
51 Variable names
52 ^^^^^^^^^^^^^^
53
54 Variables should be verbosely names, no caps, underscores with spaces. Do not just use ``i`` in for loops, again we have developers with bad eyes.
55
56 Types
57 ^^^^^
58
59 New types should use the ``_t`` postfix. Private structs should be typedef'ed and also use this.
60
61 Public Structs
62 ^^^^^^^^^^^^^^
63
64 Public structs should be typedef'ed and use the ``_st`` postfix
65
66 Conventions
67 ^^^^^^^^^^^
68
69 * use *column* instead of *field*
70 * use *schema* instead of *database*
71
72 Include Files
73 -------------
74
75 Includes that will be installed need to be written like:
76
77 .. code-block:: cpp
78
79 #include <drizzled/field/blob.h>
80
81
82 The following should only be used in cases where we are to never install these libraries in the filesystem:
83
84 .. code-block:: cpp
85
86 #include "item.h"
87
88 Comments
89 --------
90
91 Where it is not obvious what is going on. Hopefully most of the code will be self-commenting.
92
93 All code should have license headers.
94
95 Comment blocks should use the format:
96
97 .. code-block:: cpp
98
99 /* Comment Block
100 * This is a multi-line comment block
101 */
102
103 C99 style in-line and single line comments are allowed for small comments
104
105 .. code-block:: cpp
106
107 // small comment
108
109 Line lengths
110 ------------
111
112 Whilst there is no hard limit on line lengths it is recommended that lines stay under 80 characters unless going above this increases readability of the code.