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.
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.
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.
Most of the common stylistic errors can be detected by the
style checker program
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
.
l
as a variable name, because it is hard to distinguish l
from 1
on some displays.#ifdef <OS>
sections lightly. They should be treated as technical
debt and avoided when possible._WIN32
macro for conditional directives when including code using
Windows-specific API.__FreeBSD__
macro for conditional directives for FreeBSD-specific code._MSC_VER
macro for conditional directives when including code using VC++
or gcc specific extensions.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
).%m
)PRI*
and SCN*
macros in printf()/scanf() functions
for width-based integral types (uint32_t
, int64_t
, etc.).LOG(3, ...)
at the beginning of each function. Consider using higher
log level for most frequently called routines.COMPILE_ERROR_ON
and ASSERT*
macros.ERR()
macro to log error messages.#!/usr/bin/env <shell>
for portability between Linux and FreeBSD.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, obj, blk, log, vmem, vmmalloc, jemalloc,
test, doc, daxio, pmreorder, pool (for libpmempool and pmempool), rpmem
(for librpmem and rpmemd), benchmark, examples 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