Skip to content

Latest commit

 

History

History
373 lines (272 loc) · 10.1 KB

CODING_STANDARDS.md

File metadata and controls

373 lines (272 loc) · 10.1 KB
Raw

Coding Standards

This is a working document outlining the coding standard for the general MariaDB codebase. The document can be found in the 11.0 and newer trees in the root directory as "CODING_STANDARDS.md"

It does not cover the coding standards for individual plugins, these should have their own coding standards documentation.

Using Git with the MariaDB codebase

Git commit messages

Git commit messages must conform to the 50/72 rule. This is a de facto git standard which is automatically enforced by some editors. This means:

  • 50 characters max for the first (description) line (see exception later)
  • A blank line.
  • 72 characters max for every subsequent line.

In addition if there is a Jira ticket number, this should be the first thing in the description. As an example:

MDEV-12345 Fixing Rockwell Turbo Encabulator

The new principle involved is that instead of power being generated by
the relative motion of conductors and fluxes, it’s produced by the
modial interaction of magneto-reluctance and capacitive diractance.

The only explicitly allowed exception to the 50-72 rules is that if the first line can be MDEV-###### title', even if the title would make the line longer than 50 characters.

The commit messages are typically rendered in Markdown format, so markdown formatting is permitted for the message body.

Branch handling

When updating your code, please make sure you perform a rebase, not a merge with the latest branch. Pull requests should be a simple fast-forward of the branch they are intended to land on.

The correct way to rebase (if working on top of 10.3 branch):

git fetch upstream/10.3  # This assumes upstream is github.com/MariaDB/server
git rebase upstream/10.3
git push --force my_branch

Coding Style (C / C++ files)

Everyone has a preferred coding style, there is no real correct style for all projects around the world. What is important is that we stick to one common style throughout this code base.

Indentation

We should use a variant of the Allman indentation style. The variation is to use two spaces instead of tabs and has a couple of minor rule changes as below.

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.

For example:

while (x == y)
{
  something();
  somethingelse();
}
finalthing();

Switch / Case statements

For switch / case statements the case needs to be inline with the switch. Preferably switch (expr) should be followed by '{' on the same line to make the lineup of 'case:' nice:

For example:

switch(level) {
case ERROR:
  sql_print_error("Error: %s", message.c_ptr_safe());
  break;
case WARNING:
  sql_print_warning("Warning: %s", message.c_ptr_safe());
  break;
...
}

If statements

If the if statement only executes one line of code it is possible to write the statement without the braces such as this:

if (opt_console)
  opt_error_log= 0;

Prefer reducing indent level with the use of early return statements (or in special circumstances goto). Rather than:

if (condition)
{
   <logic>
}
return error_code;

Use:

if (!condition)
  return error_code;
<logic>
return success;

Functions

Consecutive functions should be separated with 2 empty lines in between

void my_function_1()
{
  <logic>
}


void my_function_2()
{
  <logic>
}

Preprocessor directives

Compiler preprocessor directives should have no indentation to them, even if in the middle of indented code. For example:

  case SSL_TYPE_NONE:                           // SSL is not required
    if (opt_require_secure_transport)
    {
      enum enum_vio_type type= vio_type(vio);
#ifdef HAVE_OPENSSL
      return type != VIO_TYPE_SSL &&
#ifndef _WIN32
             type != VIO_TYPE_SOCKET;
#else
             type != VIO_TYPE_NAMEDPIPE;
#endif
#else
#ifndef _WIN32
      return type != VIO_TYPE_SOCKET;
#else
      return type != VIO_TYPE_NAMEDPIPE;
#endif
#endif
    }

Comments reflecting the original #if condition can be appended to #else / #endif to provide additional clarity. This can be useful for large code blocks between the start and end preprocessor directives or nested preprocessor directives. For example:

#ifndef EMBEDDED_LIBRARY
...
#else /* ! EMBEDDED_LIBRARY */
...
#endif /* ! EMBEDDED_LIBRARY */

File names

File names should be lower case with underscore word separators. C file names use the .c extension, C++ files use the .cc extension and header files use the .h extension.

Language standards

For pure-C files we use C99 and for C++ we use C++11. The code need to be able to compile on multiple platforms using different compilers (for example: Windows / Linux, x86_64 / ARM).

Line lengths

Lines should be no more than 80 characters. The reason for this is that it makes it easier to have multiple editor windows open side by side and still keep code readable without line wraps.

When breaking long lines:

  • use '()' to group expressions so that the editor can automatically help you with the indentation.
  • When breaking expressions, leave the operator (+,- etc) last on the previous line.
rows= tab->table->file->multi_range_read_info(tab->ref.key, 10, 20, tab->ref.key_parts, &bufsz, &flags, &cost);
->
rows= tab->table->file->multi_range_read_info(tab->ref.key, 10, 20,
                                              tab->ref.key_parts, &bufsz,
                                              &flags, &cost);
tmp= aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa+bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
->
tmp= (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa+
      bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb);

Comments

Single line / inline code comments can use the double slash (//) style of coding, whereas multi-line code comments should use /* as a start and */ at the end, with the text indented by 2 spaces, for example:

/*
  This is a multi-line code comment.
  It has an indentation of two spaces.
*/

Variables classes, and functions

Variables and functions should be descriptive and in "snake case", for example:

void my_function(uint16 variable_name)
{

Class names should also be "snake case" but should start with an upper-case character. Such as this:

class Buffered_logs
{

Assignments should not have a space on the left side of the equals, and one space on the right hand side. For example:

a= 1;  // Correct
a = 1; // Incorrect for the server code,
       // ok for Storage Engines if they use it (aka Connect)

The above makes it easy to use 'grep' to find all assignments to a variable.

Please do not write conditions like this:

if (0 == *error_code)

Please do this instead:

if (*error_code == 0)
// Or even better
if (!*error_code)

Only use one-character variables (i,j,k...) in short loops. For anything else use descriptive names!

Variable declarations

Variables should be declared at the start of it's context (start of function, inside the 'if' statement.

The benefits of this:

  • Code lines gets shorter
  • It is easier to see the stack space used by a function.
  • It is easier to find the declaration of the variable.
  • If one has to add an 'if (error) goto end' construct, one can do that without having to move variable declarations around.

Variable initializations

Variables can be initialized using assignment operator or initializer and expression list. For Example:

int milliseconds= 1000;
char type= 't';

Or

int milliseconds{1000};
char type{'t'};

Constant integers

Constant integers that are used to define elements such as buffer sizes should be defined rather than used directly. This is because the integer could change and uses of it could be missed. For example:

char *buffer= my_malloc(PSI_INSTRUMENT_ME, 1024, MYF(MY_WME));

snprint(buffer, 1024, "%d: %s", integer, text);

Could become:

constexpr int buffer_size= 1024;
char *buffer= my_malloc(PSI_INSTRUMENT_ME, buffer_size, MYF(MY_WME));

snprint(buffer, buffer_size, "%d: %s", integer, text);

Alternatively the integer can be defined using an enum or #define.

Spacing

Whitespace

  • Lines should not have any trailing whitespace.
  • There should not be any trailing blank lines at the end of a file.
  • Line endings are POSIX style (\n).
  • Two spaces for each indentation level, not tabs.

Pointers

The * of a pointer should be on the side of the variable name such as:

void my_function(THD *thd)
{

As yet there is no standard as to whether the * in a casting should have a space or not. Both of these are valid:

name= (const char*)db_name;
name= (const char *) db_name;

Function variables

There should be a space after each comma in a definition and usage of a function. For example:

my_function(thd, db_name);

Types

In general the usage of types such as char, int and long should be discouraged but there are shortened versions of the unsigned variants available for these in my_global.h. They can be different sizes across platforms and char can be either unsigned or signed depending on platform, and therefore are not portable. Instead these should be used as appropriate:

  • 8-bit signed / unsigned int -> int8 / uint8
  • 16-bit signed / unsigned int -> int16 / uint16
  • 32-bit signed / unsigned int -> int32 / uint32
  • 64-bit signed / unsigned int -> int64 / uint64
  • Integer file descriptor -> File
  • Integer socket descriptor -> my_socket

size_t and ptrdiff_t are used in the source where appropriate, buffer sizes for example. It should be noted that these are implementation dependent but are useful when used in the correct context.

Further types can be found in the include/ directory files. There are also general utility functions in mysys.