StyleGuide.md

TimescaleDB code style guide

Source code should follow the PostgreSQL coding conventions. This includes source formatting with 4 column tab spacing and layout rules according to the BSD style.

SQL and PL/pgSQL style

There is no official SQL or PL/pgSQL style guide for PostgreSQL that we are aware of, apart from the general spacing and layout rules above. For now, try to follow the style of the surrounding code when making modifications. We might develop more stringent guidelines in the future.

Error messages

Error messages in TimescaleDB should obey the PostgreSQL error message style guide.

C style

While the PostgreSQL project mandates that C code adheres to the C89 standard with some exceptions, we've chosen to allow many C99 features for the clarity and convenience they provide. PostgreSQL sticks with C89 mostly for compatibility with many older compilers and platforms, such as Visual Studio on Windows. Visual Studio should support most of C99 nowadays, however. We might revisit this decision in the future if it turns out to be a problem for important platforms.

Unfortunately, PostgreSQL does not have a consistent style for naming of functions, variables and types. This mailing-list thread elaborates on the situation. Instead, we've tried our best to develop a consistent style that roughly follows the style of the PostgreSQL source code.

Declarations before code

C99 supports having code before a declaration, similar to C++, and we also support this in the code. For instance, the following code follows the guidelines:

void some_function()
{
    prepare();
	int result = fetch();
	...
}

Function and variable names

For clarity and consistency, we've chosen to go with lowercase under-score separated names for functions and variables. For instance, this piece of code is correct:

static void
my_function_name(int my_parameter)
{
    int my_variable;
    ...
}

while this one is wrong:

static void
MyFunctionName(int myParameter)
{
    int myVariable;
    ...
}

Type declarations

New composite/aggregate types should be typedef'd and use UpperCamelCase naming. For instance, the following is correct:

typedef struct MyType
{
    ...
} MyType;

while the following is wrong:

typedef struct my_type
{
    ...
} my_type;

Modular code and namespacing

When possible, code should be grouped into logical modules. Such modules typically resemble classes in object-oriented programming (OOP) languages and should use namespaced function and variable names that have the module name as prefix. TimescaleDB's Cache implementation is a good example of such a module where one would use

void
cache_initialize(Cache *c)
{
    ...
}

rather than

void
initialize_cache(Cache *c)
{

}

Object-orientated programming style

Even though C is not an object-oriented programming language, it is fairly straight-forward to write C code with an OOP flavor. While we do not mandate that C code has an OOP flavor, we recommend it when it makes sense (e.g., to achieve modularity and code reuse).

For example, TimescaleDB's cache.c module can be seen as a base class with multiple derived subclasses, such as hypertable_cache.c and chunk_cache.c. Here's another example of subclassing using shapes:

typedef struct Shape
{
    int color;
    void (*draw)(Shape *, Canvas *);
} Shape;

void
shape_draw(Shape *shape)
{
    /* open canvas for drawing */
    Canvas *c = canvas_open();

    /* other common shape code */
    ...

    shape->draw(shape, c);

    canvas_close(c);
}

typedef struct Circle
{
    Shape shape;
    float diameter;
} Circle;

Circle blue_circle = {
    .shape = {
        .color = BLUE,
        .draw = circle_draw,
    },
    .diameter = 10.1,
};

void
circle_draw(Shape *shape, Canvas *canvas)
{
    Circle *circle = (Circle *) shape;

    /* draw circle */
    ...
}

There are a couple of noteworthy take-aways from this example.

• Non-static "member" methods should take a pointer to the object as first argument and be namespaced as described above.
• Derived modules can expand the original type using struct embedding, in which case the "superclass" should be the first member of the "subclass", so that one can easily upcast a Circle to a Shape or, vice-versa, downcast as in circle_draw() above.
• C++-style virtual functions can be implemented with functions pointers. Good use cases for such functions are module-specific initialization and cleanup, or function overriding in a subclass.

Other noteworthy recommendations

• Prefer static allocation and/or stack-allocated variables over heap/dynamic allocation when possible. Fortunately, PostgreSQL has a nice MemoryContext implementation that helps with heap allocation when needed.
• Try to minimize the number of included headers in source files, especially when header files include other headers. Avoid circular header dependencies by predeclaring types (or use struct pointers).

For a general guide to writing C functions in PostgreSQL, you can review the section on C-language functions in the PostgreSQL documentation.

Tools and editors

We require running C code through clang-format before submitting a PR. This will ensure your code is properly formatted according to our style (which is similar to the PostgreSQL style but implement in clang-format). You can run clang-format on all of the TimescaleDB code using make format if you have clang-format (version >= 7) or docker installed.

The following Wiki post contains links to style configuration files for various editors.