Debian Codegraph @

podofo/CODING-STYLE.md

raw
1 ## Coding style
2
3 Coding style in PoDoFo follows the following general rules:
4
5 - Visual Studio formatting conventions (see for example [C# conventions](https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions)), where they apply to C/C++ like constructs
6 - Capitalized case for **public** `MethodNames()`, or private/protected methods names intended to be called outside the boundary of the current class through inheritance or class/method friendship (eg. `ProtectedMethod()`, `FriendMethod()`)
7 - Lower case for private/virtual protected methods intended to be called only within the current class, eg. `initOperation()`. It may be common to have a public outer method `MyMethod()` that performs some validations first and subsequently calls a private or virtual protected inner method `myMethod()` that actually performs the task
8 - Camel case for variables, parameters and fields (example `variableName`)
9
10 Some language specific programming stylistic choices will be hard enforced, namely:
11
12 - C style programming (`malloc`/`free`, string formatting, etc.) shall be converted to equivalent modern C++ constructs/API calls, unless there's still no other modern C++ alternative (eg. `scanf`). Where possible `new`/`delete` semantics shall be replaced by use of smart pointers
13 - `m_` and `s_` prefixes shall be used respectively for instance member and static fields/variables. For example `m_Value` or `s_instance`. No other Hungarian notation prefixes will be accepted
14 - Implicit conversion from pointer types to bool (eg. `if (!ptr)` or `while (ptr)` conditionals) shall be converted to check for `nullptr`, eg. `if (ptr == nullptr)` or `while (ptr != nullptr)`
15 - Increment/decrement operators shall always be postfixed in expressions as in `it++`, unless the prefixed operator is necessary for the correctness of an algorithm or allows to shorten/optimize the code
16
17 The following rules are lenient and are not truly enforced in all the code base, but they are still recommended to follow:
18
19 - Lower case field names for private fields used only in this class boundary, for example `m_privateField`
20 - Capitalized field names for private fields exposed by public getters/setters, example `m_Value`
21
22 All other coding conventions, covered in detail, are organized by category in the sections below.
23
24 Some examples of expected coding style can be found at the following permalinks:
25
26 - [PdfEncoding](https://github.com/podofo/podofo/blob/94145e4bd452cfd77b262dd672ec836da0c1530d/src/podofo/main/PdfEncoding.cpp)
27 - [PdfCharCodeMap](https://github.com/podofo/podofo/blob/94145e4bd452cfd77b262dd672ec836da0c1530d/src/podofo/main/PdfCharCodeMap.cpp)
28 - [PdfFontFactory](https://github.com/podofo/podofo/blob/94145e4bd452cfd77b262dd672ec836da0c1530d/src/podofo/main/PdfFontFactory.cpp)
29 - [PdfTrueTypeSubset](https://github.com/podofo/podofo/blob/94145e4bd452cfd77b262dd672ec836da0c1530d/src/podofo/private/FontTrueTypeSubset.cpp)
30
31 ### Whitespace
32 - 4-space indentation, LF line endings, UTF-8, trailing whitespace trimmed (see `.editorconfig`)
33
34 ### SPDX license headers
35 - All source files should begin with SPDX copyright and license headers:
36 ```cpp
37 // SPDX-FileCopyrightText: YEAR Author <email>
38 // SPDX-License-Identifier: LGPL-2.0-or-later OR MPL-2.0
39 ```
40
41 ### Comments and documentation
42 - `///` with at-sign `@` tags is used for Doxygen-style documentation comments on public methods
43 - Don't indent at-sign tags, put just one space after `///`
44 - Comments should be concise and avoid repetition
45
46 ### Brace and statement style
47 - Allman braces: opening brace on its own line for namespaces, classes, functions, lambdas and control-flow blocks
48 - `else`/`else if` go on a new line after the previous closing brace
49 - Single-statement `if`/`while`/`for` bodies without braces are preferred
50
51 ### Access specifiers and method organization
52 - Access specifiers should be organized in this order: `public`, `protected`, `private`
53 - Static factory methods and creation methods/constructors should appear early in the `public` section
54 - Access specifiers can be repeated to separate groups of functionalities
55 - Private methods may have more permissive preconditions and skip validation that public methods perform
56 - Trivial one-line/simple expression getter methods are allowed to be implemented inline in header files
57
58 ### Method naming patterns
59 - `Try*` prefix for methods that return `bool` to indicate success/failure (e.g., `TryGetGID()`, `TryConvertToUtf8()`)
60 - `Must*` prefix for methods that throw on failure instead of returning bool (e.g., `MustGetKey()`, `MustFindKey()`)
61 - `Get*` for simple accessor methods that may return nullptr or throw
62 - `Find*` for lookup methods that search through collections or hierarchies
63 - `Add*` for methods that insert/append items
64 - `Remove*` for methods that delete items
65 - `Set*` for setter methods
66 - `Is*` or `Has*` for boolean query methods
67 - `*Unsafe` suffix for private methods that bypass safety checks or assume preconditions
68 - `*NoDirtySet` suffix for internal methods that modify state without setting dirty flags
69
70 ### Const correctness
71 - Const correctness is generally enforced everywhere (an exception is accessing the document `PdfIndirectObjectList` instance)
72 - Both const and non-const overloads are provided for accessor methods that return references or pointers (e.g., `GetKey()`, `FindKey()`)
73 - Const methods should not modify object state, except for mutable members used for caching/lazy loading
74
75 ### Namespace usage
76 - `using namespace std;` and `using namespace PoDoFo;` are used in implementation files (.cpp) for brevity
77 - `using namespace` is not used in header files
78
79 ### PoDoFo specifics
80
81 - `PdfElement` inheritors shall not have a public constructor accepting `PdfDocument` as an argument. Such constructors are infrastructural only
82 - `PdfDictionary` and other methods doing lookups on `PdfName` with keys known at compile time: `GetKey`, `FindKey`, `FindKeyHas`, `HasKey`, `RemoveKey` methods (and in general non addition lookup methods) take string literals or `string_view`. For `AddKey`, `AddKeyIndirect`, `AddKeyIndirectSafe` the `_n` user literal is used
83 - `std::string_view` are always passed by const reference in the public API
84
85 ### Friend declarations
86 - `friend` declarations are used to grant access to related classes (e.g., `friend class PdfDocument;`)
87 - The `PODOFO_PRIVATE_FRIEND` macro is used for private (not part of the public API) implementation classes
88
89 ### Constructors and move semantics
90 - Constructor arguments are generally stored as class fields. Static `Create*()` factory methods are preferred when member fields need to be synthesized from constructor arguments
91 - `shared_ptr<T>` are generally passed by value in public constructors and by r-value `shared_ptr<T>&&` references in private constructors/methods
92 - `noexcept` is used on move operations
93
94 ### Header conventions
95 - Include guards take the `#ifndef PDF_*_H` / `#define ... / #endif` form
96 - Public classes and free functions intended to be exported are annotated with `PODOFO_API`
97 - `final` is applied to classes and helper types (iterators, parameter structs) that are not designed for inheritance
98 - PoDoFo classes are forward-declared inside `namespace PoDoFo { ... }` at the top of a header when a full include can be avoided
99
100 ### `.cpp` file layout
101 - Include order: `<podofo/private/PdfDeclarationsPrivate.h>` first, then the matching own header, then system, 3rd-party and other PoDoFo headers, generally in that order
102 - Right after `using namespace std;` / `using namespace PoDoFo;`, `static` forward prototypes for translation-unit-local helpers are declared, with their definitions placed later in the file
103 - Translation-unit-local types are placed in an anonymous `namespace { ... }`; translation-unit-local free functions are marked `static`
104
105 ### Enums
106 - An explicit underlying type is always declared, e.g. `enum class PdfXxx : uint8_t`. The minimum size required should be used for regular enums, while flags shall use `uint32_t`
107 - The first enumerator is conventionally a sentinel: `Unknown = 0` for value enums, `None = 0` for flag enums
108 - For bitmask-style enums, the operators are declared by placing `ENABLE_BITMASK_OPERATORS(PoDoFo::PdfXxxFlags);` outside the `PoDoFo` namespace, near the bottom of the header
109
110 ### Errors, asserts, logging
111 - Throwing shall be done with the following macros:
112 - `PODOFO_RAISE_ERROR(PdfErrorCode::X)` for plain throws
113 - `PODOFO_RAISE_ERROR_INFO(PdfErrorCode::X, "msg {}", ...)` when a formatted message is needed
114 - `PODOFO_RAISE_LOGIC_IF(cond, "msg")` for guarded `InternalLogic` throws
115 - `PODOFO_PUSH_FRAME` / `PODOFO_PUSH_FRAME_INFO` are used to add frames to an existing `PdfError`
116 - `PODOFO_ASSERT(cond)` is used for debug-only sanity checks and `PODOFO_INVARIANT(cond)` to document invariants without runtime cost
117 - Logging goes through `PoDoFo::LogMessage(PdfLogSeverity::..., "msg {}", ...)`
118
119 ### Comment markers
120 - `// NOTE:` explanatory notes worthy of attention
121 - `// TODO:` for planned work
122 - `// FIXME:` for known defects
123 - `// CHECK-ME:` for code that should be reviewed/validated
124
125 They should be kept short (one or two lines).