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.

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)

Formatting

Indentation

• Tab size 4, indent 4, tabs as spaces
• Curly braces on their own line
• Keywords public, protected and private indented with two spaces

Spacing

• Operators + - * / % = == != < > <= >=
  • surrounded by spaces
  • excepted after 'operator' keyword
• References and pointers: int& x, int* p
• No spaces around brackets
• No spaces around parenthesis, 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

Style

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.