This document defines the coding style of the Daala project. In general, Daala tries to conform to C89, and avoid features which are not available in C89 in portable code. We try to minimize our dependence on libc (e.g., using macros around memory allocation functions).
The top of each file should contain the following license header:
/*Daala video codec Copyright (c) 2001-2013 Daala project contributors. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.*/
Make sure the copyright years are up to date.
In general, it is not necessary to list invididual copyright holders in each file (beyond "Daala project contributors"). Xiph does not require assignment of copyright.
Non-const global variables in portable code are not allowed. They make it impossible to write re-entrant code without introducing a dependency on a threading library.
All functions and types use the canonical C naming scheme: all lowercase with
underscores for separators.
#defines and global const variables use all uppercase with
underscores for separators.
All functions and types begin with an od_ prefix.
All #defines and global const variables begin with an
OD_ prefix.
Do not prefix names with single letters indicating their role (m for member variables, k for constants, g for globals, etc.).
Do not use leading or trailing underscores in regular code.
Macro definitions which need to declare local variables should append two trailing underscores to their name to avoid conflicts with regular code.
Initialization and deinitialization routines for type od_foo are
named od_foo_init() and od_foo_clear().
These should take an already-allocated pointer to an object of the appropriate
type.
If allocating versions of these functions are desired, they should be named
od_foo_create() and od_foo_free(), and dispatch to
od_foo_init() and od_foo_clear() respectively.
There are no tabs in source code. Do not use them, ever.
Remove all trailing whitespace at the end of a line.
Use two-space indenting.
Lines should be no more than 79 characters. This allows them to be displayed fully in a standard terminal even in diffs. The extra column on the right also makes long lines easier to spot.
= operators, function
parameters, etc.
Do not add additional indentation to indicate open parentheses, etc.
If this produces lines you think are confusing, break them up into multiple
statements.
Prefer wrapping at lower-precedence operators.
Prefer making wrapped lines as close in length as possible, while minimizing the total number of lines.
All unary operators and the binary operators +, -,
&&, and || belong to the start of the next
line, not the end of the previous line.
struct fields and local variables
One variable/field per declaration (e.g., do not use
int x, y, z;).
Do not attempt to align variable/field names.
Do not initialize variables in the declaration. This makes it harder to follow C89's "no declarations after a statement" rule and can hide logic errors that would be exposed by valgrind.
Do not use C++ comments (//).
Write properly punctuated comments that start with a capital letter.
Do not put comments to the right of code. Put them on a separate line.
Format multi-line comments as follows:
/*This is a multi-line comment.
Each sentence starts on a new line, and all subsequent lines in the same
sentence are indented a single space, making it easier to change the comment
without re-flowing a whole paragraph.
This gives better "blame" information, and makes diffs easier to read.
Other notes:
- Start the first sentence on the same line as the start of the comment, and
do not add a space in front of it.
The former ensures that single-line and multi-line comments have the same
style, making it easier to convert between the two.
The latter maximizes the space available for prose in heavily-indented
code.
- Align the start of subsequent sentences with the start of the first one.
- End the comment on the same line as the last sentence, and do not add an
extra space after that sentence.*/
All pre-processor statements begin with a # in the leftmost
column.
Indent pre-processor statements by adding spaces after the #, not
before it.
Preprocessor statements inside an
#if/#else/#endif block are indented by
one space per level (after the leading #).
Use #if [!]defined(X) instead of #if[n]def X.
The former makes it easier to extend to multiple conditions, zero out, etc.,
e.g., replacing
#if defined(X)with
#if defined(X) && 0
There should never be more than a single blank line in a row.
Do not add blank lines in the interior of a function, except inside of a multi-line comment. If you find yourself wanting to do this, use two functions instead.
All non-unary operators with the precedence of + and
- or less should have one space on either side, except for
commas, which have a single following space.
There is no space before the opening parenthesis of a function call argument list, nor after a closing parenthesis followed by a comma or a semicolon.
Semicolons in for loop iterators also have a single following
space, except when the following statement is empty.
The * in pointer types hugs the variable name, not the type name.
Opening braces go on the same line as the start of the construct they are
opening (function body, if, else, for,
do, while, switch, etc.), separated by
a single space.
Do not put spaces in empty braces.
Closing braces go on a line by themselves, indented at the same level as the opening line.
If an array initializer fits on a single line, put a single space inside the brace on each end.
If an array initializer does not fit on a single line, do not wrap it as one long line. Instead, start a new line after the opening brace and indent the initialization data. Start new lines of initialization data as necessary, without the additional one space used to indent wrapped lines.
For multi-line multidimensional array initializers, place the comma on the same line as the closing brace for the inner array, and start the opening brace for the next element of the outer array on a new line.
Do not include trailing commas in array initializers, enums, or other lists. These cause warnings on some platforms.
Do not use syntactically unnecessary parentheses unless they would generate a warning with gcc or MSVC.
Parentheses should be placed around every single-expression macro definition, including constants.
A single space follows if, for, while,
and switch keywords, before the parenthesized expression.
An else and the while in a do ...
while loop begin on a new line, instead of being placed on the
same line as the closing brace from the previous block.
If the else's statement is a subsequent if, that
if is placed on the same line as the else.
If you omit the break after a non-empty case
statement where control reaches the end of the block, add a comment indicating
you are falling through.
If control reaches the end of the block in the last case statement
in a switch block, do not omit the break.
Use braces around the body of a case statement, unless the body is
a single statement (excluding the break) and fits on one line
(including the break).
Loop or conditional bodies with a single statement may be placed on the same
line as the start of the loop/conditional without any braces.
Such loops can easily be stepped over in a debugger.
This is allowed even for if statements with an else
clause.
If a loop/conditional body has to extend to multiple lines for any reason
(including exceeding the 79-character line limit, even if still a single
statement), then it must be contained in braces (and the first statement start
on a new line).
Use for (;;) for infinite loops, not while (1).
Some compilers complain about conditional expressions that always evaluate to
true.
return values are separated from the keyword by a single space,
and are not enclosed in parentheses.
for (i = 0; i < n; i++) x[i] = 0;
do something(); while (!done);
while (!done) {
do_something();
do_something_else();
}
if (test) do_this(); else do_that();
if (condition) {
do_one_thing();
then_another();
}
else if (another_condition) do_something_else();
switch (value) {
case 1: {
int foo;
foo = compute_foo();
use_foo(foo);
break;
}
case 2: ignore_foo();
/*Fall through.*/
case 3: return -1;
default: handle_default(); break;
}
Put the return type and parameters on the same line as the function name, wrapping as necessary. Do not attempt to align the function names in a group of functions with different return types.
If the function is associated with a single object, put that object first.
If the function has both inputs and outputs, the outputs go before the inputs (like memcpy(), which was designed to mimic the assignment operator).
When taking a variable-length array, the length/size/stride of the array goes after the pointer to the array.
All header files should be wrapped in a define guard as follows:
#if !defined(_path_file_H) # define _path_file_H (1) ... #endifPath elements should be sparated by underscores. The leading
src component of the path is omitted.
Path/file names should be lower case (as identifiers which match
_[A-Z].* are reserved by POSIX).
Do not forward declare things in order to avoid additional includes. Processing includes is fast in C, unlike C++, where they contain most of the code, and recompiling C is also fast. It's not worth the maintenance burden of having one thing defined in many places to avoid including some extra files.
In header files which have circular dependencies, put any typedefs at the top, before including the headers which produce the cycle.
Do not put inline functions in headers except in platform-specific sections. The inline keyword is not available in C89. Do not use static functions in headers as a substitute, as they generate warnings if unused.