diff options
Diffstat (limited to '')
| -rw-r--r-- | src/pmdk/CODING_STYLE.md | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/src/pmdk/CODING_STYLE.md b/src/pmdk/CODING_STYLE.md new file mode 100644 index 000000000..9b0cfa736 --- /dev/null +++ b/src/pmdk/CODING_STYLE.md @@ -0,0 +1,140 @@ +# C Style and Coding Standards for Persistent Memory Development Kit + +This document defines the coding standards and conventions for writing +PMDK code. To ensure readability and consistency within the code, +the contributed code must adhere to the rules below. + +### Introduction +The Persistent Memory Development Kit coding style is quite similar to the style +used for the SunOS product. +A full description of that standard can be found +[here.](https://www.cis.upenn.edu/~lee/06cse480/data/cstyle.ms.pdf) + +This document does not cover the entire set of recommendations and formatting rules +used in writing PMDK code, but rather focuses on some PMDK-specific conventions, +not described in the document mentioned above, as well as the ones the violation +of which is most frequently observed during the code review. +Also, keep in mind that more important than the particular style is **consistency** +of coding style. So, when modifying the existing code, the changes should be +coded in the same style as the file being modified. + +### Code formatting +Most of the common stylistic errors can be detected by the +[style checker program](https://github.com/pmem/pmdk/blob/master/utils/cstyle) +included in the repo. +Simply run `make cstyle` or `CSTYLE.ps1` to verify if your code is well-formatted. + +Here is the list of the most important rules: +- The limit of line length is 80 characters. +- Indent the code with TABs, not spaces. Tab width is 8 characters. +- Do not break user-visible strings (even when they are longer than 80 characters) +- Put each variable declaration in a separate line. +- Do not use C++ comments (`//`). +- Spaces around operators are mandatory. +- No whitespace is allowed at the end of line. +- For multi-line macros, do not put whitespace before `\` character. +- Precede definition of each function with a brief, non-trivial description. +(Usually a single line is enough.) +- Use `XXX` tag to indicate a hack, problematic code, or something to be done. +- For pointer variables, place the `*` close to the variable name not pointer type. +- Avoid unnecessary variable initialization. +- Never type `unsigned int` - just use `unsigned` in such case. +Same with `long int` and `long`, etc. +- Sized types like `uint32_t`, `int64_t` should be used when there is an on-media format. +Otherwise, just use `unsigned`, `long`, etc. +- Functions with local scope must be declared as `static`. + +### License & copyright +- Make sure you have the right to submit your contribution under the BSD license, +especially if it is based upon previous work. +See [CONTRIBUTING.md](https://github.com/pmem/pmdk/blob/master/CONTRIBUTING.md) for details. +- A copy of the [BSD-style License](https://github.com/pmem/pmdk/blob/master/LICENSE) +must be placed at the beginning of each source file, script or man page +(Obviously, it does not apply to README's, Visual Studio projects and \*.match files.) +- When adding a new file to the repo, or when making a contribution to an existing +file, feel free to put your copyright string on top of it. + +### Naming convention +- Keep identifier names short, but meaningful. One-letter variables are discouraged. +- Use proper prefix for function name, depending on the module it belongs to. +- Use *under_score* pattern for function/variable names. Please, do not use +CamelCase or Hungarian notation. +- UPPERCASE constant/macro/enum names. +- Capitalize first letter for variables with global or module-level scope. +- Avoid using `l` as a variable name, because it is hard to distinguish `l` from `1` +on some displays. + +### Multi-OS support (Linux/FreeBSD/Windows) +- Do not add `#ifdef <OS>` sections lightly. They should be treated as technical +debt and avoided when possible. +- Use `_WIN32` macro for conditional directives when including code using +Windows-specific API. +- Use `__FreeBSD__` macro for conditional directives for FreeBSD-specific code. +- Use `_MSC_VER` macro for conditional directives when including code using VC++ +or gcc specific extensions. +- In case of large portions of code (i.e. a whole function) that have different +implementation for each OS, consider moving them to separate files. +(i.e. *xxx_linux.c*, *xxx_freebsd.c* and *xxx_windows.c*) +- Keep in mind that `long int` is always 32-bit in VC++, even when building for +64-bit platforms. Remember to use `long long` types whenever it applies, as well +as proper formatting strings and type suffixes (i.. `%llu`, `ULL`). +- Standard compliant solutions should be used in preference of compiler-specific ones. +(i.e. static inline functions versus statement expressions) +- Do not use formatting strings that are not supported by Windows implementations +of printf()/scanf() family. (like `%m`) +- It is recommended to use `PRI*` and `SCN*` macros in printf()/scanf() functions +for width-based integral types (`uint32_t`, `int64_t`, etc.). + +### Debug traces and assertions +- Put `LOG(3, ...)` at the beginning of each function. Consider using higher +log level for most frequently called routines. +- Make use of `COMPILE_ERROR_ON` and `ASSERT*` macros. +- Use `ERR()` macro to log error messages. + +### Unit tests +- There **must** be unit tests provided for each new function/module added. +- Test scripts **must** start with `#!/usr/bin/env <shell>` for portability between Linux and FreeBSD. +- Please, see [this](https://github.com/pmem/pmdk/blob/master/src/test/README) +and [that](https://github.com/pmem/pmdk/blob/master/src/test/unittest/README) +document to get familiar with +our test framework and the guidelines on how to write and run unit tests. + +### Commit messages +All commit lines (entered when you run `git commit`) must follow the common +conventions for git commit messages: +- The first line is a short summary, no longer than **50 characters,** starting + with an area name and then a colon. There should be no period after + the short summary. +- Valid area names are: **pmem, pmem2, obj, blk, log, + test, doc, daxio, pmreorder, pool** (for *libpmempool* and *pmempool*), **rpmem** + (for *librpmem* and *rpmemd*), **benchmark, examples, core** and **common** (for everything else). +- It is acceptable for the short summary to be the only thing in the commit + message if it is a trivial change. Otherwise, the second line must be + a blank line. +- Starting at the third line, additional information is given in complete + English sentences and, optionally, bulleted points. This content must not + extend beyond **column 72.** +- The English sentences should be written in the imperative, so you say + "Fix bug X" instead of "Fixed bug X" or "Fixes bug X". +- Bullet points should use hanging indents when they take up more than + one line (see example below). +- There can be any number of paragraphs, separated by a blank line, as many + as it takes to describe the change. +- Any references to GitHub issues are at the end of the commit message. + +For example, here is a properly-formatted commit message: +``` +doc: fix code formatting in man pages + +This section contains paragraph style text with complete English +sentences. There can be as many paragraphs as necessary. + +- Bullet points are typically sentence fragments + +- The first word of the bullet point is usually capitalized and + if the point is long, it is continued with a hanging indent + +- The sentence fragments don't typically end with a period + +Ref: pmem/issues#1 +``` |