@@ -399,7 +399,105 @@ disclosure of security bugs. In those cases, please go through the process
399399outlined on that page and do not file a public issue.
400400
401401## Coding Style
402+ It's a pretty long topic, which is difficult to summarize in a single paragraph.
403+ As a rule of thumbs, try to imitate the coding style of
404+ similar lines of codes around your contribution.
405+ The following is a non-exhaustive list of rules employed in zstd code base:
406+
407+ ### C90
408+ This code base is following strict C90 standard,
409+ with 2 extensions : 64-bit `long long` types, and variadic macros.
410+ This rule is applied strictly to code within `lib/` and `programs/`.
411+ Sub-project in `contrib/` are allowed to use other conventions.
412+
413+ ### C++ direct compatibility : symbol mangling
414+ All public symbol declarations must be wrapped in `extern “C” { … }`,
415+ so that this project can be compiled as C++98 code,
416+ and linked into C++ applications.
417+
418+ ### Minimal Frugal
419+ This design requirement is fundamental to preserve the portability of the code base.
420+ #### Dependencies
421+ - Reduce dependencies to the minimum possible level.
422+ Any dependency should be considered “bad” by default,
423+ and only tolerated because it provides a service in a better way than can be achieved locally.
424+ The only external dependencies this repository tolerates are
425+ standard C libraries, and in rare cases, system level headers.
426+ - Within `lib/`, this policy is even more drastic.
427+ The only external dependencies allowed are `<assert.h>`, `<stdlib.h>`, `<string.h>`,
428+ and even then, not directly.
429+ In particular, no function shall ever allocate on heap directly,
430+ and must use instead `ZSTD_malloc()` and equivalent.
431+ Other accepted non-symbol headers are `<stddef.h>` and `<limits.h>`.
432+ - Within the project, there is a strict hierarchy of dependencies that must be respected.
433+ `programs/` is allowed to depend on `lib/`, but only its public API.
434+ Within `lib/`, `lib/common` doesn't depend on any other directory.
435+ `lib/compress` and `lib/decompress` shall not depend on each other.
436+ `lib/dictBuilder` can depend on `lib/common` and `lib/compress`, but not `lib/decompress`.
437+ #### Resources
438+ - Functions in `lib/` must use very little stack space,
439+ several dozens of bytes max.
440+ Everything larger must use the heap allocator,
441+ or require a scratch buffer to be emplaced manually.
442+
443+ ### Naming
444+ * All public symbols are prefixed with `ZSTD_`
445+ + private symbols, with a scope limited to their own unit, are free of this restriction.
446+ However, since `libzstd` source code can be amalgamated,
447+ each symbol name must attempt to be (and remain) unique.
448+ Avoid too generic names that could become ground for future collisions.
449+ This generally implies usage of some form of prefix.
450+ * For symbols (functions and variables), naming convention is `PREFIX_camelCase`.
451+ + In some advanced cases, one can also find :
452+ - `PREFIX_prefix2_camelCase`
453+ - `PREFIX_camelCase_extendedQualifier`
454+ * Multi-words names generally consist of an action followed by object:
455+ - for example : `ZSTD_createCCtx()`
456+ * Prefer positive actions
457+ - `goBackward` rather than `notGoForward`
458+ * Type names (`struct`, etc.) follow similar convention,
459+ except that they are allowed and even invited to start by an Uppercase letter.
460+ Example : `ZSTD_CCtx`, `ZSTD_CDict`
461+ * Macro names are all Capital letters.
462+ The same composition rules (`PREFIX_NAME_QUALIFIER`) apply.
463+ * File names are all lowercase letters.
464+ The convention is `snake_case`.
465+ File names **must** be unique across the entire code base,
466+ even when they stand in clearly separated directories.
467+
468+ ### Qualifiers
469+ * This code base is `const` friendly, if not `const` fanatical.
470+ Any variable that can be `const` (aka. read-only) **must** be `const`.
471+ Any pointer which content will not be modified must be `const`.
472+ This property is then controlled at compiler level.
473+ `const` variables are an important signal to readers that this variable isn’t modified.
474+ Conversely, non-const variables are a signal to readers to watch out for modifications later on in the function.
475+ * If a function must be inlined, mention it explicitly,
476+ using project's own portable macros, such as `FORCE_INLINE_ATTR`,
477+ defined in `lib/common/compiler.h`.
478+
479+ ### Debugging
480+ * **Assertions** are welcome, and should be used very liberally,
481+ to control any condition the code expects for its correct execution.
482+ These assertion checks will be run in debug builds, and disabled in production.
483+ * For traces, this project provides its own debug macros,
484+ in particular `DEBUGLOG(level, ...)`, defined in `lib/common/debug.h`.
485+
486+ ### Code documentation
487+ * Avoid code documentation that merely repeats what the code is already stating.
488+ Whenever applicable, prefer employing the code as the primary way to convey explanations.
489+ Example 1 : `int nbTokens = n;` instead of `int i = n; /* i is a nb of tokens *./`.
490+ Example 2 : `assert(size > 0);` instead of `/* here, size should be positive */`.
491+ * At declaration level, the documentation explains how to use the function or variable
492+ and when applicable why it's needed, of the scenarios where it can be useful.
493+ * At implementation level, the documentation explains the general outline of the algorithm employed,
494+ and when applicable why this specific choice was preferred.
495+
496+ ### General layout
402497* 4 spaces for indentation rather than tabs
498+ * Code documentation shall directly precede function declaration or implementation
499+ * Function implementations and its code documentation should be preceded and followed by an empty line
500+
403501
404502## License
405503By contributing to Zstandard, you agree that your contributions will be licensed
0 commit comments