| 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. |