-# Bluedroid Style Guide
-This document outlines the coding conventions and code style used in Bluedroid.
+# Fluoride Style Guide
+This document outlines the coding conventions and code style used in Fluoride.
Its primary purpose is to provide explicit guidance on style so that developers
are consistent with one another and spend less time debating style.
## Directory structure
-Directories at the top-level should consist of major subsystems in Bluedroid.
+Directories at the top-level should consist of major subsystems in Fluoride.
Each subsystem's purpose should be documented in the `doc/directory_layout.md`
file, even if it seems obvious from the name.
`include/` must also have a subdirectory named `foo/`.
## Target architecture
-Bluedroid targets a variety of hardware and cannot make many assumptions about
+Fluoride targets a variety of hardware and cannot make many assumptions about
memory layout, sizes, byte order, etc. As a result, some operations are
considered unsafe and this section outlines the most important ones to watch out
for.
pointers have the same type.
## Language
-Bluedroid is written in C99 and should take advantage of the features offered by
+Fluoride is written in C99 and should take advantage of the features offered by
it. However, not all language features lend themselves well to the type of
-development required by Bluedroid. This section provides guidance on some of the
+development required by Fluoride. This section provides guidance on some of the
features to embrace or avoid.
### C Preprocessor
the `2^n` build configurations is untenable for `n` greater than, say, 4.
### C++
-Although C++ offers constructs that may make Bluedroid development faster,
+Although C++ offers constructs that may make Fluoride development faster,
safer, more pleasant, etc. the decision _for the time being_ is to stick with
pure C99. The exceptions are when linking against libraries that are written
in C++. At the time of writing these libraries are `gtest` and `tinyxml2`,
Use booleans to represent boolean state, instead of a set of masks into an
integer. It's more transparent and readable, and less error prone.
+### Function names as strings
+C99 defines `__func__` as an identifier that represents the function's name
+in which it is used. The magic identifier `__FUNCTION__` should not be used
+as it is a non-standard language extension and an equivalent standardized
+mechanism exists. In other words, use `__func__` over `__FUNCTION__`.
+
+## Fluoride conventions
+This section describes coding conventions that are specific to Fluoride.
+Whereas the _Language_ section describes the use of language features, this
+section describes idioms, best practices, and conventions that are independent
+of language features.
+
+### Memory management
+Use `osi_malloc` or `osi_calloc` to allocate bytes instead of plain `malloc`.
+Likewise, use `osi_free` over `free`. These wrapped functions provide additional
+lightweight memory bounds checks that can help track down memory errors.
+
+By convention, functions that contain `*_new` in their name are allocation
+routines and objects returned from those functions must be freed with the
+corresponding `*_free` function. For example, list objects returned from
+`list_new` should be freed with `list_free` and no other freeing routine.
+
+### Asserts
+Use `assert` liberally throughout the code to enforce invariants. Assertions
+should not have any side-effects and should be used to detect programming logic
+errors.
+
+At minimum, every function should assert expectations on its arguments. The
+following example demonstrates the kinds of assertions one should make on
+function arguments.
+```
+ size_t open_and_read_file(const char *filename, void *target_buffer, size_t max_bytes) {
+ assert(filename != NULL);
+ assert(filename[0] != '\0');
+ assert(target_buffer != NULL);
+ assert(max_bytes > 0);
+
+ // function implementation begins here
+ }
+```
+
## Header files
In general, every source file (`.c` or `.cpp`) in a `src/` directory should
have a corresponding header (`.h`) in the `include/` directory.
OSDN Git Service
