110 строки
4.1 KiB
Markdown
110 строки
4.1 KiB
Markdown
Development Guide
|
|
=================
|
|
|
|
Coding Conventions
|
|
------------------
|
|
|
|
* **DO** use fixed length types defined in `stdint.h` instead
|
|
of language keywords determined by the compiler (e.g., `int64_t, uint8_t`, not
|
|
`long, unsigned char`).
|
|
|
|
* **DO** use `const` and `static` and visibility modifiers to scope exposure of
|
|
variables and methods as much as possible.
|
|
|
|
* **DO** use doxygen comments, with \[in,out\]
|
|
[direction annotation](http://www.doxygen.nl/manual/commands.html#cmdparam) in all public API
|
|
headers. This is also encouraged, but not strictly required, for internal API
|
|
headers as well.
|
|
|
|
* **DO** disable doxygen documentation for elements that are not in the public
|
|
API as described [here](./refman/doxygen-howto.md#disable-doxygen).
|
|
|
|
* **DON'T** use global variables where possible.
|
|
|
|
* **DON'T** use abbreviations unless they are already well-known terms known by
|
|
users (e.g., "app", "info"), or are already required for use by developers (e.g.,
|
|
"min", "max", "args"). Examples of bad use would be `num_widgets` instead of
|
|
`widget_count`, and `opt_widgets` instead of `option_widgets` or `optional_widgets`.
|
|
|
|
* **DON'T** use the same C function name with two different prototypes across
|
|
the project where possible.
|
|
|
|
Style Guide
|
|
-----------
|
|
|
|
### Automated Formatting with `clang-format`
|
|
|
|
For all C/C++ files (`*.c`, `*.cpp` and `*.h`), we use `clang-format` (specifically
|
|
version 3.6) to apply our code formatting rules. After modifying C/C++ files and
|
|
before merging, be sure to run:
|
|
|
|
```sh
|
|
$ ./scripts/format-code
|
|
```
|
|
|
|
This allows us to apply formatting choices such as the use of [Allman style](
|
|
http://en.wikipedia.org/wiki/Indent_style#Allman_style) braces and the 80
|
|
character column width consistently.
|
|
|
|
Please stage the formatting changes with your commit, instead of making an extra
|
|
"Format Code" commit. Your editor can likely be set up to automatically run
|
|
`clang-format` across the file or region you're editing. See:
|
|
|
|
- [clang-format.el](https://github.com/llvm-mirror/clang/blob/master/tools/clang-format/clang-format.el) for Emacs
|
|
- [vim-clang-format](https://github.com/rhysd/vim-clang-format) for Vim
|
|
- [vscode-cpptools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
|
|
for Visual Studio Code
|
|
|
|
The [.clang-format](../.clang-format) file describes the style that is enforced
|
|
by the script, which is based off the LLVM style with modifications closer to
|
|
the default Visual Studio style. See [clang-format style options](
|
|
http://releases.llvm.org/3.6.0/tools/clang/docs/ClangFormatStyleOptions.html)
|
|
for details.
|
|
|
|
### License Header
|
|
|
|
The following license header **must** be included at the top of every code file:
|
|
|
|
```
|
|
// Copyright (c) Microsoft Corporation
|
|
// SPDX-License-Identifier: MIT
|
|
```
|
|
|
|
It should be prefixed with the file's comment marker. If there is a compelling
|
|
reason to not include this header, the file can be added to
|
|
`.check-license.ignore`.
|
|
|
|
All files are checked for this header with the script:
|
|
|
|
```sh
|
|
$ ./scripts/check-license
|
|
```
|
|
|
|
### Naming Conventions
|
|
|
|
Naming conventions we use that are not automated include:
|
|
|
|
1. Use `lower_snake_case` for variable, member/field, and function names.
|
|
2. Use `UPPER_SNAKE_CASE` for macro names and constants.
|
|
3. Prefer `lower_snake_case` file names for headers and sources.
|
|
4. Prefer full words for names over contractions (i.e., `memory_context`, not
|
|
`mem_ctx`).
|
|
5. Prefix names with `_` to indicate internal and private fields or methods
|
|
(e.g., `_internal_field, _internal_method()`).
|
|
6. The single underscore (`_` ) is reserved for local definitions (static,
|
|
file-scope definitions).
|
|
e.g., static ebpf_result_t _do_something(..).
|
|
7. Prefix `struct` definitions with `_` (this is an exception to point 6), and always create a `typedef` with the
|
|
suffix `_t`. For example:
|
|
```c
|
|
typedef struct _ebpf_widget
|
|
{
|
|
uint64_t count;
|
|
} ebpf_widget_t;
|
|
```
|
|
8. Prefix eBPF specific names in the global namespace with `ebpf_` (e.g., `ebpf_result_t`).
|
|
|
|
Above all, if a file happens to differ in style from these guidelines (e.g.,
|
|
private members are named `m_member` rather than `_member`), the existing style
|
|
in that file takes precedence.
|