<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE doc SYSTEM "doc.dtd">
<doc title="{[project]}" subtitle="Coding Standards" toc="y">
    <description>{[project]} Coding Standard.</description>

    <!-- ======================================================================================================================= -->
    <section id="uncrustify">
        <title>Formatting with <proper>uncrustify</proper></title>

        <p><backrest/> uses <proper>uncrustify</proper> to check/update the code formatting. If the <id>code-format</id> test fails in CI then reformat the code:</p>

        <code-block>
            pgbackrest/test/test.pl --code-format
        </code-block>

        <p>Also review the standards in the following sections below. Some standards require further explanation and others are not enforced by <proper>uncrustify</proper>.</p>

    </section>

    <!-- ======================================================================================================================= -->
    <section id="standards">
        <title>Standards</title>

        <!-- =================================================================================================================== -->
        <section id="indentation">
            <title>Indentation</title>

            <p>Indentation is four spaces -- no tabs. Only file types that absolutely require tabs (e.g. `Makefile`) may use them.</p>
        </section>

        <!-- =================================================================================================================== -->
        <section id="line-length">
            <title>Line Length</title>

            <p>With the exception of documentation code, no line of any code or test file shall exceed 132 characters. If a line break is required, then it shall be after the first function parenthesis:</p>

            <code-block>
// CORRECT - location of line break after first function parenthesis if line length is greater than 132
StringList *removeList = infoBackupDataLabelList(
    infoBackup, strNewFmt("^%s.*", strZ(strLstGet(currentBackupList, fullIdx))));

// INCORRECT
StringList *removeList = infoBackupDataLabelList(infoBackup, strNewFmt("^%s.*", strZ(strLstGet(currentBackupList,
    fullIdx))));
            </code-block>

            <p>If a conditional, then after a completed conditional, for example:</p>

            <code-block>
// CORRECT - location of line break after a completed conditional if line length is greater than 132
if (archiveInfoPgHistory.id != backupInfoPgHistory.id ||
    archiveInfoPgHistory.systemId != backupInfoPgHistory.systemId ||
    archiveInfoPgHistory.version != backupInfoPgHistory.version)

// INCORRECT
if (archiveInfoPgHistory.id != backupInfoPgHistory.id || archiveInfoPgHistory.systemId !=
    backupInfoPgHistory.systemId || archiveInfoPgHistory.version != backupInfoPgHistory.version)
            </code-block>
        </section>

        <!-- =================================================================================================================== -->
        <section id="function-comment">
            <title>Function Comments</title>

            <p>Comments for <code>extern</code> functions should be included in the <file>.h</file> file. Comments for <code>static</code> functions and implementation-specific notes for <code>extern</code> functions (i.e., not of interest to the general user) should be included in the <file>.c</file> file.</p>
        </section>

        <!-- =================================================================================================================== -->
        <section id="inline-comment">
            <title>Inline Comment</title>

            <p>Inline comments shall start at character 69 and must not exceed the line length of 132. For example:</p>

            <code-block>
typedef struct InlineCommentExample
{
    const String *comment;                                          // Inline comment example
    const String *longComment;                                      // Inline comment example that exceeds 132 characters should
                                                                    // then go to next line but this should be avoided
} InlineCommentExample;
            </code-block>
        </section>

        <!-- =================================================================================================================== -->
        <section id="naming">
            <title>Naming</title>

            <!-- =============================================================================================================== -->
            <section id="variables">
                <title>Variables</title>

                <p>Variable names use camel case with the first letter lower-case.</p>

                <list>
                    <list-item><id>stanzaName</id> - the name of the stanza</list-item>
                    <list-item><id>nameIdx</id> - loop variable for iterating through a list of names</list-item>
                </list>

                <p>Variable names should be descriptive. Avoid <id>i</id>, <id>j</id>, etc.</p>
            </section>

            <!-- =============================================================================================================== -->
            <section id="types">
                <title>Types</title>

                <p>Type names use camel case with the first letter upper case:</p>

                <p><code>typedef struct MemContext &lt;...&gt;</code></p>

                <p><code>typedef enum {&lt;...&gt;} ErrorState;</code></p>
            </section>

            <!-- =============================================================================================================== -->
            <section id="constants">
                <title>Constants</title>

                <p><b>#define Constants</b></p>

                <p><code>#define</code> constants should be all caps with <id>_</id> separators.</p>

                <code-block type="c">
#define MY_CONSTANT                                                 "STRING"
                </code-block>

                <p>The value should be aligned at column 69 whenever possible.</p>

                <p>This type of constant should mostly be used for strings. Use enums whenever possible for integer constants.</p>

                <p><b>String Constants</b></p>

                <p>String constants can be declared using the <code>STRING_STATIC()</code> macro for local strings and <code>STRING_EXTERN()</code> for strings that will be externed for use in other modules.</p>

                <p>Externed strings should be declared in the header file as:</p>

                <code-block type="c">
#define SAMPLE_VALUE                                                "STRING"
    STRING_DECLARE(SAMPLE_VALUE_STR);
                </code-block>

                <p>And in the C file as:</p>

                <code-block type="c">
STRING_EXTERN(SAMPLE_VALUE_STR,                                     SAMPLE_VALUE);
                </code-block>

                <p>Static strings declared in the C file are not required to have a <code>#define</code> if the <code>#define</code> version is not used. Externed strings must always have the <code>#define</code> in the header file.</p>

                <p><b>Enum Constants</b></p>

                <p>Enum elements follow the same case rules as variables. They are strongly typed so this shouldn't present any confusion.</p>

                <code-block type="c">
typedef enum
{
    cipherModeEncrypt,
    cipherModeDecrypt,
} CipherMode;
                </code-block>

                <p>Note the comma after the last element. This reduces diff churn when new elements are added.</p>
            </section>

            <!-- =============================================================================================================== -->
            <section id="macros">
                <title>Macros</title>

                <p>Macro names should be upper-case with underscores between words. Macros (except simple constants) should be avoided whenever possible as they make code less clear and test coverage harder to measure.</p>

                <p>Macros should follow the format:</p>

                <code-block type="c">
#define MACRO(paramName1, paramName2)   \
    &lt;code&gt;
                </code-block>

                <p>If the macro defines a block it should look like:</p>

                <code-block type="c">
#define MACRO_2(paramName1, paramName2) \
{                                       \
    &lt;code&gt;                              \
}
                </code-block>

                <p>Continuation characters should be aligned at column 132 (unlike the examples above that have been shortened for display purposes).</p>

                <p>To avoid conflicts, variables in a macro will be named <id>[macro name]_[var name]</id>, e.g. <id>TEST_RESULT_resultExpected</id>. Variables that need to be accessed in wrapped code should be provided accessor macros.</p>

                <p><link section="/language-elements/variadic-functions">Variadic functions</link> are an exception to the capitalization rule.</p>
            </section>

            <!-- =============================================================================================================== -->
            <section id="begin-end">
                <title>Begin / End</title>

                <p>Use <id>Begin</id> / <id>End</id> for names rather than <id>Start</id> / <id>Finish</id>, etc.</p>
            </section>

            <!-- =============================================================================================================== -->
            <section id="new-free">
                <title>New / Free</title>

                <p>Use <id>New</id> / <id>Free</id> for constructors and destructors rather than <id>Create</id> / <id>Destroy</id>, etc.</p>
            </section>
        </section>

        <!-- =================================================================================================================== -->
        <section id="formatting">
            <title>Formatting</title>

            <!-- =============================================================================================================== -->
            <section id="braces">
                <title>Braces</title>

                <p>C allows braces to be excluded for a single statement. However, braces should be used when the control statement (if, while, etc.) spans more than one line or the statement to be executed spans more than one line.</p>

                <p>No braces needed:</p>

                <code-block type="c">
if (condition)
    return value;
                </code-block>

                <p>Braces needed:</p>

                <code-block type="c">
if (conditionThatUsesEntireLine1 &amp;&amp;
    conditionThatUsesEntireLine2)
{
    return value;
}
                </code-block>

                <code-block type="c">
if (condition)
{
    return
        valueThatUsesEntireLine1 &amp;&amp;
        valueThatUsesEntireLine2;
}
                </code-block>

                <p>Braces should be added to <code>switch</code> statement cases that have a significant amount of code. As a general rule of thumb, if the code block in the <code>case</code> is large enough to have blank lines and/or multiple comments then it should be enclosed in braces.</p>

                <code-block type="c">
switch (int)
{
    case 1:
        a = 2;
        break;

    case 2:
    {
        # Comment this more complex code
        a = 1;
        b = 2;

        c = func(a, b);

        break;
    }
}
                </code-block>
            </section>

            <!-- =============================================================================================================== -->
            <section id="hints-warnings-errors">
                <title>Hints, Warnings, and Errors</title>

                <p>Hints are to be formatted with capitalized <id>HINT:</id> followed by a space and a sentence. The sentence shall only begin with a capital letter if the first word is an acronym (e.g. TLS) or a proper name (e.g. PostgreSQL). The sentence must end with a period, question mark or exclamation point as appropriate.</p>

                <p>Warning and errors shall be lowercase with the exceptions for proper names and acronyms and end without punctuation.</p>
            </section>
        </section>
    </section>

    <!-- ======================================================================================================================= -->
    <section id="language-elements">
        <title>Language Elements</title>

        <!-- =================================================================================================================== -->
        <section id="data-types">
            <title>Data Types</title>

            <p>Don't get exotic - use the simplest type that will work.</p>

            <p>Use <id>int</id> or <id>unsigned int</id> for general cases. <id>int</id> will be at least 32 bits. When not using <id>int</id> use one of the types defined in <file>common/type.h</file>.</p>
        </section>

        <!-- =================================================================================================================== -->
        <section id="macros">
            <title>Macros</title>

            <p>Don't use a macro when a function could be used instead. Macros make it hard to measure code coverage.</p>
        </section>

        <!-- =================================================================================================================== -->
        <section id="objects">
            <title>Objects</title>

            <p>Object-oriented programming is used extensively. The object pointer is always referred to as <id>this</id>.</p>

            <p>An object can expose internal struct members by defining a public struct that contains the members to be exposed and using inline functions to get/set the members.</p>

            <p>The header file:</p>

            <code-block type="c">
/***********************************************************************************************************************************
Getters/setters
***********************************************************************************************************************************/
typedef struct ListPub
{
    unsigned int listSize;                                          // List size
} ListPub;

// List size
FN_INLINE_ALWAYS unsigned int
lstSize(const List *const this)
{
    return THIS_PUB(List)->listSize;
}
            </code-block>

 <p><code>THIS_PUB()</code> ensures that <code>this != NULL</code> so there is no need to check that in the calling function.</p>

            <p>And the C file:</p>

            <code-block type="c">
struct List
{
    ListPub pub;                                                    // Publicly accessible variables
    ...
};
            </code-block>

            <p>The public struct must be the first member of the private struct. The naming convention for the public struct is to add <id>Pub</id> to the end of the private struct name.</p>
        </section>

        <!-- =================================================================================================================== -->
        <section id="variadic-functions">
            <title>Variadic Functions</title>

            <p>Variadic functions can take a variable number of parameters. While the <code>printf()</code> pattern is variadic, it is not very flexible in terms of optional parameters given in any order.</p>

            <p>This project implements variadic functions using macros (which are exempt from the normal macro rule of being all caps). A typical variadic function definition:</p>

            <code-block type="c">
typedef struct StoragePathCreateParam
{
    bool errorOnExists;
    bool noParentCreate;
    mode_t mode;
} StoragePathCreateParam;

#define storagePathCreateP(this, pathExp, ...)                              \
    storagePathCreate(this, pathExp, (StoragePathCreateParam){__VA_ARGS__})
#define storagePathCreateP(this, pathExp)                                  \
    storagePathCreate(this, pathExp, (StoragePathCreateParam){0})

void storagePathCreate(const Storage *this, const String *pathExp, StoragePathCreateParam param);
            </code-block>

            <p>Continuation characters should be aligned at column 132 (unlike the example above that has been shortened for display purposes).</p>

            <p>This function can be called without variable parameters:</p>

            <code-block type="c">
storagePathCreateP(storageLocal(), "/tmp/pgbackrest");
            </code-block>

            <p>Or with variable parameters:</p>

            <code-block type="c">
storagePathCreateP(storageLocal(), "/tmp/pgbackrest", .errorOnExists = true, .mode = 0777);
            </code-block>

            <p>If the majority of functions in a module or object are variadic it is best to provide macros for all functions even if they do not have variable parameters. Do not use the base function when variadic macros exist.</p>
        </section>
    </section>

    <!-- ======================================================================================================================= -->
    <section id="testing">
        <title>Testing</title>

        <!-- =================================================================================================================== -->
        <section id="uncoverable-uncovered">
            <title>Uncoverable/Uncovered Code</title>

            <!-- =============================================================================================================== -->
            <section id="uncoverable">
                <title>Uncoverable Code</title>

                <p>The <id>uncoverable</id> keyword marks code that can never be covered. For instance, a function that never returns because it always throws an error. Uncoverable code should be rare to non-existent outside the common libraries and test code.</p>

                <code-block type="c">
}   // {uncoverable - function throws error so never returns}
                </code-block>

                <p>Subsequent code that is uncoverable for the same reason is marked with <code>// {+uncoverable}</code>.</p>
            </section>

            <!-- =============================================================================================================== -->
            <section id="uncovered">
                <title>Uncovered Code</title>

                <p>Marks code that is not tested for one reason or another. This should be kept to a minimum and an excuse given for each instance.</p>

                <code-block type="c">
exit(EXIT_FAILURE); // {uncovered - test harness does not support non-zero exit}
                </code-block>

                <p>Subsequent code that is uncovered for the same reason is marked with `// {+uncovered}`.</p>
            </section>
        </section>
    </section>
</doc>