Coding Standards

= Layout =

Indent Levels
Indent level is done with 2 spaces (a vimrc collection that does our style can be found here: http://hg.tangent.org/vimrc

(Someone needs to answer how to get Emacs to do this)) M-x customize-variable c-basic-offset

No tabs are to be used in any files except Makefile.am files There you should lead off with a tab but complete indention with spaces.

Brace Placement
for (...) { foo }

For if/else place the else on a separate line from the braces. If you find that you are commenting a section of code feel free to use this style:

/* Some explanation */ { something }

In general it is better to be more verbose. Verbose code has a higher chance of surviving code rewrites since the next developer will understand it.

= Types =


 * Please use stdint.h for now. Wikipedia on stdint
 * When writing new code always use the C99 types. GCC will give us lint like advice if we do.
 * Use bool, not my_bool.
 * Use true and false, not TRUE and FALSE (those macros need to die).
 * ulong -> uint32_t
 * ulonglong uint64_t
 * long int -> int32_t

Why? Long is not portable and in MySQL there are a number of places where we use it that I question if the code is really 64 bit clean.

Please use true/false with bools, not numbers (I really wish gcc would flag this). Also, when testing true and false be descriptive.

if (can_print == false) {...};

or

if (not can_print) {...}

Over

if (!(can_print)) {..};

Also, booleans should have a leading verb to make clear that it is boolean. Instead of "valid", use "is_valid". Instead of "drivers", use "has_drivers".

= Pointers =

Use NULL when referring to the null pointer, not 0.

= Code Style =

When assigning please use MySQL style (no space before equals sign, one space after):

x= 4;

It is easy to search for.

Instead of something together like this:

if (a == b && c ==j || A)  do_something;

Do it like:

if (((a == b) && (c ==j)) || A ) do_something;

Be generous with your use of parentheses. If I see them, then I know you knew what you were doing and I do not have to worry if you really understood operator precedent.

Encapsulate structures and classes.

Use enum, not defines. Defines are for single shot "everything will be this". Enums create lists. If the values are going to go into a switch/ case... they should be enums.

Please do not use "i" as an iterator in for loops. I have old eyes... use x or spell out a variable.

Please fix indention in old code. It is a boring thing to do, but is incredibly valuable. When someone looks at code, they will send in patches based on what they see. Lets make it so the code looks identical.

Empty for loops
When you use a for loop to iterate across something and do not actually do anything in the for loop (for instance, if you just want to walk an array or list of pointers): do this:

for {};

or

for {/* Do nothing */};

DO NOT do this:

for ;

Why? When you have an empty body. It gives a hint that you really did want just the for to loop.

Ignoring return types
Generally, return types of a function should not be ignored, however, if you do ignore the return, do:

(void)func;

This indicates explicitly that you are ignoring the return and know that you are ignoring the return. This will be discouraged.

Include File Headers
If you are editing the file drizzled/plugin_authentication.h

You would use the following:


 * 1) ifndef DRIZZLED_PLUGIN_AUTHENICATION_H
 * 2) define DRIZZLED_PLUGIN_AUTHENICATION_H


 * 1) endif /* DRIZZLED_PLUGIN_AUTHENICATION_H */

Please always place a comment on the #endif.

Assert
Use standard assert for now. We have an option in the configure.ac file to turn this off for production uses. In general you should be liberal with your use of assert.

= Naming Style =

Structures should be named as "something_st". All structures which are use in a global context should by typedef'ed.

Name classes in caps style. Such as Table or TableShare.

Enums should be used and should always have its members in all caps. The declaration type should be done in lower case.

Bools should be named "is_something" or "has_something".

Methods should begin with a lower case verb explaining the action. "foo.setBar" or "foo.replaceString".

= File Organization =

Class/Structure File Conventions
All new classes get their own .h and .cc files. We will need to pull apart the mess that exists today, but that is a long term goal.

Linking
Do not use ../ linking in Makefile.am to reuse a a single object from another library. If you need to link to the library, then link to the library. Also, do not create symbolic links between libraries.

Directory Naming
Everything in the code is an item for the potential to have plugins. We will keep a clean naming scheme for this reason.

For the server the naming is "drizzled"

So an install will be: /usr/local/include/drizzled/

Client library: /usr/local/include/libdrizzle


 * Why drizzled over just plain drizzle?

If we add extensions to the command line library they will go into "drizzle"


 * Ramifications for includes?

Includes that will be installed need to be written like:
 * 1) include 

The use of:


 * 1) include "item.h"

Should only be used in cases where we are to never install these libraries in the filesystem.

TODO: Work out "error" condition in includes if a build of the server uses an "include" from the install path (aka we want to make sure we only use the includes in our directory).

= Other =

Avoid #ifdef except for real portability needs.

Never conditionally define a member variable or method of a struct/class using #ifdefs

Structures should be typedef'ed as name_st.

Use enum, not define.

For if/else use the following bracket style:

if (something) { something; } else { something_else; }

Stile del codice