filament/CODE_STYLE.md

# Filament Code style and Formatting

Filament largely uses Android's code style, which is significantly different from the
Google code style and is derived from the Java code style, but not quite.

The guiding principles of the filament code style and code formatting can be resumed as:
- no nonsense
- use your own judgement
- break the rules **if it makes sense** e.g.: it improves readability substantially
- use the formatting of the file you're in, even if it breaks the rules
- no nonsense

## Formatting

- 4 spaces indent
- 8 spaces continuation indent
- 100 columns
- `{` at the end of the line
- spaces around operators and after `;`
- class access modifiers are not indented
- last line of `.cpp` or `.h` file must be an empty line

```c++
for (int i = 0; i < max; i++) {
}

class Foo {
public:
protected:
private:
};

```

## Naming Conventions

### Files

- headers use the `.h` extension
- implementation files use the `.cpp` extension
- included files use the `.inc` extension
- class files bear the name of the class they implement
- **no spaces** in file names
- file names must be treated as case **insensitive**, i.e. it is not allowed to have several files
  with the same name but a different case
- `#include` must use **fully qualified** names
- use `#include < >` for all public (exported) headers
- use `#include " "` for private headers
- all *public* include files must reside under the `include` folder
- all *source* files must reside under the `src` folder
- tests reside under the `test` folder
- public headers of a `foo` library must live in a folder named `foo`

```
libfoo.so

include/foo/FooBar.h
src/FooBar.cpp
src/data.inc

#include <foo/FooBar.h>
#include "FooBarPrivate.h"
```

### Code

- Everything is camel case except constants
- `constants` are uppercase and don't have a prefix
- `global` variables prefixed with `g`
- `static` variables prefixed with `s`
- `private` and `protected` class attributes prefixed with `m`
- `static` class attributes prefixed with `s`
- `public` class attributes *are not* prefixed
- class attributes and methods are lower camelcase

```c++
extern int gGlobalWarming;

class FooBar {
public:
    FooBar(int attributeName, int sizeInBytes)
            : mAttributeName(attributeName),
              sizeInBytes(sizeInBytes) {}

    void reallyLongMethodNameWithLotsOfArguments(bool argument1,
            int someSecondArgument, int bestArgument) {
        std::pair<bool, int> pair = {
            argument1,
            argument2,
        };
        // etc
    }

    int sizeInBytes;
private:
    int mAttributeName;
    static int sGlobalAttribute;
    static constexpr int FOO_COUNT = 10;
    enum {
        ONE, TWO, THREE
    };
};
```

## Code Style

### Files

- always include the copyright notice at the top of every file
- make sure the date is correct

```c++
/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
```

### Headers

- **always** include a class' header **first** in the `.cpp` file
- other headers are sorted in reverse order of their layering, that is, lower layer headers last
- within a layer, headers are sorted alphabetically
- strive for implementing one class per file
- `STL` limited in **filament** public headers to:
    - `array`
    - `initializer_list`
    - `iterator`
    - `limits`
    - `optional`
    - `type_traits`
    - `utility`
    - `variant`

For **libfilament** the rule of thumb is that STL headers that don't generate code are allowed (e.g. `type_traits`),
conversely containers and algorithms are not allowed. There are exceptions such as `array`. See above for the full list.
- The following `STL` headers are banned entirely, from public and private headers as well as implementation files:
  - `iostream`


*Sorting the headers is important to help catching missing `#include` directives.*

```c++
/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

// Bar.cpp

#include <foo/Bar.h>

#include "PrivateStuff.h"

#include <foo/Alloc.h>
#include <foo/Bar.h>

#include <utils/compiler.h>

#include <algorithm>
#include <iostream>

#include <assert.h>
#include <string.h>
```

### Strings

- Never use `std::string` in the Filament core renderer. Prefer `utils::CString` or `std::string_view`.
- When using `std::string` in tools, always include the `std::` qualifier to disambiguate it
  from other string types.

### Misc

- Use `auto` only when the type appears on the same line or with iterators and lambdas.
```c++
auto foo = new Foo();
for (auto& i : collection) { }
```