@@ -399,7 +399,105 @@ disclosure of security bugs. In those cases, please go through the process
399
399
outlined on that page and do not file a public issue.
400
400
401
401
## 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
402
497
* 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
+
403
501
404
502
## License
405
503
By contributing to Zstandard, you agree that your contributions will be licensed
0 commit comments