| 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). |