** This coding style is not final and not yet in effect.  Discussion ongoing in #openvpn-devel.  Right before branching of the release/2.4 branch, we will have The Great Reformatting where we switch to this coding style. **

= Introduction =

The OpenVPN coding style is based on the Allman style, e.g.:
{{{#!c
void myfunction(int a, int b)
{
    if (a == b)
    {
        something_equals();
    }
    else
    {
        does_not_equal();
    }
}
}}}

Summarizing:
 * Indentation is 4 spaces, no tabs ever.
 * Opening and closing brackets get their own line, and must match indentation.

   Open question: do we allow `} else {` and `} else if () {` as exceptions?

 * Line length is 80 characters.
 * C99 is allowed.  E.g. `for (int i = 0; i < max; i++)`.
 * Only use `/* */`-style comments

   Open question:  should we also allow `//` for single-line comments now that we can write C99?

= Line wrapping =
The maximum line length is 80 characters.  When lines exceed this length, wrap them using a double indent (ie 8 spaces) on the new line.  For example:
{{{#!c
void my_function(void)
{
    if (variable_with_artificially_long_name_1 != 0
            && variable_with_artificially_long_name_2 != 0)
    {
        return variable_with_artificially_long_name_1
                + variable_with_artificially_long_name_2
                + variable_with_artificially_long_name_3;
    }
}
}}}

If you find yourself continuously exceeding the line limit, you might want to consider breaking up your function into smaller functions to reduce nesting.

= Some additional secure coding style rules =

This are **style rules**, ''not'' general secure coding guide lines.  See e.g. https://www.securecoding.cert.org/confluence/display/c/SEI+CERT+C+Coding+Standard for useful guidelines on writing secure C.

== All branches should use braces ==

For example:
{{{#!c
if (a)
{
    return true;
}
}}}

We wouldn't be the first to not spot missing braces in an if statement, like what happened in Apple's [[https://www.imperialviolet.org/2014/02/22/applebug.html|goto fail;]] bug.  Always using braces prevents this kind of mistake.

== Cases in a switch statement should break or explicitly fall through ==

The only exception to this rule are empty case statements, to not overly clutter the code with comments.

For example:
{{{#!c
switch (a)
{
    case ONE:
    case TWO:
        one_or_two = true;
        /* Fall through */
    case THREE:
        now_do_something();
        break;
    default:
        ASSERT(0);
}
}}}

This makes the intent immediately clear to the reader / reviewer.

= GNU Indent rules =
to get the above effect, use
{{{
gindent -kr -bl -nce -nbc -l80 file.c
}}}
(though other options might be needed, work in progress)

Indent likes to produce artifacts, though, because it really really likes putting the return type on the same line as the function name, which creates long and messy declarations for many functions in tun.c (my test candidate).

A slightly less brutal tool (because it can be told to just leave certain constructs alone, while changing others) seems to be

{{{
uncrustify -c config tun.c
}}}

... but that one has a zillion of options (600)... some options for a start
{{{
indent_columns=4
indent_with_tabs=2
indent_braces=false
indent_else_if=false
indent_switch_case=2
indent_label=-2
sp_before_sparen=add
sp_inside_sparen=remove
nl_if_brace=add
nl_brace_else=add
nl_elseif_brace=add
nl_else_brace=add
nl_else_if=remove
nl_func_type_name=add
code_width=80
mod_full_brace_if=add
mod_full_brace_if_chain=false
mod_add_long_ifdef_endif_comment=20
mod_add_long_ifdef_else_comment
cmt_c_nl_end=true
cmt_star_cont=true
pp_indent=add 
}}}