Coding Style

Note: This document describes the coding style and conventions used across MariaDB Server. It is maintained by the MariaDB Foundation and evolves over time as conventions are clarified and extended.
Suggestions and proposed changes are welcome. Please raise them on the developers mailing list (developers@lists.mariadb.org) so they can be discussed in the open before being incorporated.

Indentation

Core MariaDB Server uses a variant of the Allman indentation style. The indentation is 2 spaces. Avoid tabs.

The 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, 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, header files use the .h extension.

Language standards

MariaDB Server must compile on all supported operating systems and Linux distributions. Thus the limiting factor is the compiler on the oldest supported distribution. Currently MariaDB 11.4 must use C99 and C++11 standards, while 11.8 uses C++17.

Line lengths

Lines should generally be no longer than 80 characters. For example,

rows= tab->table->file->multi_range_read_info(tab->ref.key, 10, 20, tab->ref.key_parts, &bufsz, &flags, &cost);

should be changed to

rows= tab->table->file->multi_range_read_info(tab->ref.key, 10, 20,
                                              tab->ref.key_parts,
                                              &bufsz, &flags, &cost);

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;

Avoid conditions like this:

if (0 == *error_code)

Use this instead:

if (!*error_code)

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

Variable initialization

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

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. For example:

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

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

Could become:

constexpr uint 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)
{

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

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.

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.