Coding Philosophy and Guidelines

This document summarizes the coding guidelines in appleseed. This is a perpetual work in progress.

Philosophy

• We believe in collective code ownership. All the code belongs to everyone. Feel free to fix or improve any part of the code.

• We believe in continuous refactoring. If you come across something that you feel is not as good as it could be (be it code, documentation, test data...) make a note to yourself or open an issue in the tracker and come back to it later, or improve it right away.

• We believe in clean code. Code quality and readability is of utmost importance. Choose your class, method and variable names carefully, keep the code consise, respect the coding conventions, pay attention to formatting and to the order of declarations, etc.

• We believe in code reviews. We need to share the knowledge of the code, and make sure it is as good as it can possibly be. We'll ask you to review our code and we'll ask to review yours.

• We believe in fearless coding. Don't get scared of experimenting and hacking your way around. Unit tests, integration tests and Git are all there to make sure you don't break things.

• For documentation like for code: don't repeat yourself.

• Know when to break these rules. Software development cannot be reduced to a strict set of rules. Be measured and reasonable.

Formatting

Source Files

• Header files must have a .h extension and source files must have a .cpp extension.
• All header and source files must begin and end with an empty line.
• All header and source files must contain an up-to-date licensing information.

Indentation

• Tab size 4, indent 4, tabs as spaces.
• Curly braces on their own line.
• Keywords public, protected and private indented with two spaces.
• Preprocessor directives such as #ifdef, #endif, #pragma, etc. must be left-aligned (no indentation).

Spacing

• Operators + - * / % = == != < > <= >=
  • surrounded by spaces
  • excepted after 'operator' keyword.
• References and pointers: int& x, int* p.
• No spaces around brackets.
• No spaces around parentheses, excepted after control flow keywords (if for while do).
• No space before commas, one space after commas.
• During definition, template <...> statements go on their one line.

Naming Conventions

• Namespaces: a single (preferably short) word in lower case
  • excepted for namespaces hiding implementation details in header files: in this case, add a _impl suffix: namespace thread_impl.
• Types, enums, unions, structs, classes, public constants: CamelCaps.
• Functions, variables, class methods and members:
  • lower case, words separated with underscores
  • global variables: g_ prefix
  • class members: m_ prefix
    • excepted in the following classes: foundation::Vector, foundation::Matrix, foundation::Color and foundation::AABB
    • excepted for private implementation (impl).

Coding Style

#include statements

Group #include statements by category (in this order):

1. In .cpp files, start by including the matching header file.
2. Then comes appleseed.renderer header files, if any.
3. Then appleseed.foundation header files, if any.
4. Then header files from third party libraries, if any.
5. Then standard header files.

Within each category, keep all #include statements ordered alphabetically.

Usage of struct and class

Use struct only for trivial classes, otherwise stick to class, even if all members are public. The goal is to simplify forward declarations, where it is mandatory to use the same keyword (struct or class) as in the definition.

inline keyword

In general, don't declare functions/methods inline, but define them as inline.

const keyword

Use const copiously. Everything that can be const should be const, including integral parameters of functions and methods.

override keyword

Just like const, use OVERRIDE (our portable version of C++11's override) every time it makes sense.

You will need to include foundation/platform/compiler.h to make sure OVERRIDE is properly defined on all platforms.

Comments

• Comments on their own lines start with a capital letter and end with a period.
• Comments on the same line as code start with a lower case letter and don't end with a period.

Code Examples

// This function foo is as weird as it is useless.
template <typename T>
inline void foo(void* ptr, const size_t size)
{
    delete [] ptr;  // no need to check if ptr is null
}

User Interfaces

As far as possible, we are following Apple Human Interface Guidelines.