This file describes the coding style and guidelines used by this repository, which must be followed for any new code.
- Variables, functions, methods, class members, namespaces, files: lowerCamelCase
- Classes, structs, enum classes, enum values, aliases, constexpr, static class variables: UpperCamelCase
- C-style defines: ALL_CAPS_WITH_UNDERSCORE_TO_SEPARATE_WORDS
- Class member names should start with an underscore
- Static variables should start with s_
- When enumerating a map/unordered_map using a for loop, name the iterator loop variable somethingKV (key/value)
- Always use the full namespace for types used to declare observer and delegate methods in public APIs, so the user overriding the methods doesn't have to type all of them manually
- Prohibit C-style cast, use static_cast instead
- Prohibit C-style types (int, long, char), use cstdint types instead (std::int32_t, std::int8_t)
- Prohibit typedef keyword, use using instead
- Prohibit C-style enums, use enum class instead
- Always initialize non static data members (NSDM) except when impossible (when the data member is a reference), using brace initialization
- Always initialize structs fields using brace initialization to prevent UB in cases like this:
// Start with a struct defined like this
struct Foo
{
int a;
};
// Declare a variable bar of type Foo using aggregate initialization
auto const bar = Foo{5};
// At a later time, a new field is added to Foo so that it's now defined like this
struct Foo
{
int a;
int b;
};
// !!! The previously declared bar variable will still compile, as it is using aggregate initialization, but it will now have an unitialized field without knowing it !!!
// No such UB would have happened if Foo was defined like this
struct Foo
{
int a{0};
int b{0};
};- Always specify the type to the right of the = sign when declaring a variable (and always use the = sign for the sake of consistency). Since c++17 and [dcl.init], there is no downside to this rule.
- Always use auto for variables declaration as it's impossible to have an uninitialized variable (possible since c++17 thanks to [dcl.init] update in P0135R1: Guaranteed copy elision)
- Always put const to the right of the type (for consistency and prevent ambiguity when used with auto and pointers)
- Add virtual and override keywords when overriding a virtual method for clarity and consistency
- Always declare function parameters as const (so they cannot be changed inside the function), except for obvious reasons (references, movable objects and pointers that are mutable)
- Always declare variables as const if they never change
- Current library public headers (using "")
- Current library private headers (using "")
- Other non-standard libraries public headers (using <>)
- Standard libraries public headers (using <>)
Separate each category with an empty line feed.
Example:
#include "la/avdecc/avdecc.hpp"
#include "entity.hpp"
#include <windows.h>
#include <boost/boost.hpp>
#include <vector>- Don't use function parameter to return a value (except for in/out objects, but never for simple types), use the return value of the function (use pair/tuple/struct/optional if required). Except if absolutely required.
- A non-owning pointer passed to a function should be declared as & if required and * if optional
- Never pass a shared_pointer directly if the function does not participate in ownership (taking a count in the reference)
- Never pass to a function a dereferenced non local shared_pointer (sptr.get() or *sptr, where sptr is global or is class member that can be changed by another thread or sub-function). Take a reference count before dereferencing.
- Always handle all cases in a switch-case statement (make use of the default keyword if required)
- Always scope statement blocs with curling braces when it's optional (if, else, ...)
Use the provided clang-format file to correctly format the code.
- A patched version of the clang-format binary is required (fixing issues in baseline code)
- clang-format version 7.0.0 (with the patch applied: clang-7.0.0-BraceWrappingBeforeLambdaBody.patch)
- Precompiled clang-format with patch applied, for windows and macOS, can be found here
TBD / WIP