Guidelines

This chapter collects the internal guidelines for maintaining and extending this library.

The documents in this section describe how source code, APIs, documentation, and supporting files should be written and structured. Their purpose is to ensure that the entire project remains consistent, readable, maintainable, and easy to understand for both contributors and long-term maintainers.

These guidelines are primarily intended for:

• maintainers,

• contributors,

• and developers working on the library itself.

If you are only using the library in your own applications, most of these documents are not required reading. However, they may still provide useful insights into the design philosophy and architectural decisions behind the project.

• Erbsland C++ Code Style
  • Formatting
  • Naming
  • Files and Includes
  • CMake
  • Comments and API Documentation
    • Comment Format
    • Required Documentation
    • Cryptographic Implementations
    • Test Status
  • Class Organization
  • Modern C++
  • Erbsland Core Integration
• CMake Build Files Structure
• Guidelines for File Structures
  • Relation File vs. Type
  • Splitting Implementation over Multiple Files
  • Forward Declarations
  • Out-of-Line Implementations
  • Include Ownership
  • Optional Standard-Library Formatters
  • Directories and Namespaces
  • Separating Implementation Details from the Public API
• Platform Integration Guidelines
  • General Rules
    • Recommended Pattern
  • Strings and Buffers
  • Platform Notes
  • Tests
• ReStructuredText Style
  • Header Style
  • Linking Symbols
• Topic Page Guidelines
  • What are Good Topic Pages?
  • File Structure
  • Page Structure
  • Recommended Workflow to Create the Content
  • Recommended Writing Style
  • Anti-Patterns
  • Related Guidelines
• Reference Page Guidelines
  • File Structure
  • Page Structure
  • Related Guidelines
• Writing Style
  • General Guidelines
    • Topic Pages
• Guidelines for Writing Demos
  • Purpose of Demos
  • Demo Executable Behavior
  • Demo Code in Documentation Pages
  • Language and Themes in Demos
  • Code Style, API Usage and Theming
• Guidelines for Writing Examples and Demos
  • Code Style
    • In General
    • For Demos
  • API Usage
  • Language and Themes in Example Code
  • Unicode and Emojis
• Themes and Languages for Examples and Demos
  • Theme Selection
  • Demo Content Inspirations
    • Nature & Environment
    • Animals & Wildlife
    • Earth & Space
    • Science & Mathematics
    • Games & Puzzles
    • Fantasy & Adventure
    • Music & Sound
  • Natural Language in Examples
• Bad Code and Anti-Patterns
  • Severity
  • Automated Scanner
  • Accepted Locations
  • Anti-Pattern Catalog
    • Files Longer Than 500 Lines
    • Anonymous Namespaces
    • Classes and Structs in the Wrong Files or Units
    • Namespaces in the Wrong Units
    • Implementations in the Wrong Units
    • Oversized Nested Types
    • Forward Declarations at the Usage Location
    • Static Global Object Construction
    • Classes with Only Static Methods
    • Missing API Documentation
    • Missing Default Group Comment
    • Multiple Classes, Structs, or Enums in a Header
    • Regular Literal Strings for Erbsland Core APIs
    • Silencing nodiscard with static_cast<void>(...)
    • Inefficient and Unnecessary Conversions or Copies
    • Nested Namespace Blocks and End Comments
• Cryptographic Algorithm Documentation
  • Specification Mapping
  • Security-Relevant Decisions
  • Secret Lifetime
• How to Write API Guidelines
  • Why API Guidelines
  • Common Principles
  • Main Page Structure
  • Structural Validation
  • Anti-Patterns
  • Related Guidelines
• Common API Guidelines
  • Pattern Placeholder Definitions
  • Common Patterns
  • Additional Name Principles
  • Exception and Error Handling
  • Test Status Markers
  • Domain-Specific Page Guidelines
  • Related Guidelines
• Block Geometry Domain API Guidelines
  • Core Semantics
    • Coordinate Model
  • Primary Types
  • Secondary Types
  • Pattern Definitions
  • Value Object Patterns
  • State and Membership Patterns
  • Geometry Arithmetic Patterns
  • Direction and Ring Patterns
  • Layout Patterns
  • Iteration and Division Patterns
• Geometry API Guidelines
  • Primary Types
  • Secondary Types
  • Value Object Patterns
• Configuration Domain API Guidelines
  • Core Semantics
    • Validation Rule Model
  • Primary Types
  • Value and Document Types
  • Source and Trust Types
  • Validation Rules Types
  • Error Types
  • Pattern Definitions
  • Value Access Patterns
  • Document Construction Patterns
  • Parsing Patterns
  • Validation Rule Construction Patterns
  • Source and Trust Patterns
• Core Application API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Lifecycle Patterns
  • Customization Patterns
  • Application-Part Patterns
  • Application Service Patterns
  • Application Instance Patterns
  • Metadata and Error Patterns
• Cryptology Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • X.509 Identity Patterns
  • Hash Selection Patterns
  • Hashing Patterns
  • Message Authentication Patterns
  • Key Derivation Patterns
  • Symmetric Encryption Patterns
  • Cryptology Configuration Patterns
  • TLS Configuration Parser Patterns
  • Protected Data Patterns
  • Key Agreement Patterns
  • Password Hashing Patterns
  • X.509 Certificate Patterns
  • Signature Verification Patterns
  • TLS 1.3 Record Protection Patterns
• Color Terminal Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Buffer Types
  • Drawing Types
  • Input Types
  • Terminal Integration Types
  • Document Types
  • Pattern Definitions
  • Block and Style Patterns
  • Buffer Read Patterns
  • Buffer Write Patterns
  • Cursor Write Patterns
  • Terminal Patterns
  • Input Patterns
  • Interactive Read Patterns
  • Document Rendering Patterns
• Error Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Pattern Definitions
  • Exception Patterns
  • Error Context Patterns
  • Throw Helper Patterns
• Event Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Event Value Types
  • Scheduling and Thread Types
  • Backend Types
  • Pattern Definitions
  • Event Value Patterns
  • Dispatch Patterns
  • Subscription Patterns
  • Event Loop Patterns
  • Timer and Thread Patterns
  • Backend Patterns
• Internationalization API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Map Patterns
  • Translator Patterns
• Log Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Manager Patterns
  • Producer Patterns
  • Writer Patterns
• Math Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Pattern Definitions
  • Saturating Arithmetic Patterns
  • Integer Utility Patterns
  • Big Integer Patterns
  • Saturating Value Patterns
  • Range and Bounded Value Patterns
• Memory Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Compression Types
  • Pattern Definitions
  • Internal Byte Tool Patterns
  • Byte Value Patterns
  • Byte Sequence Read Patterns
  • Mutable Byte Sequence Patterns
  • Shared Block Patterns
  • Integer Access Patterns
  • Sequential Read and Write Patterns
  • Ring Buffer Patterns
  • Byte Compression Patterns
  • Sensitive Byte Storage Patterns
  • Shared Storage Patterns
• Compiled Resource API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Lookup Patterns
  • Metadata Patterns
• Network Domain API Guidelines
  • Core Semantics
    • HTTP Values
  • Primary Types
  • Secondary Types
  • Address Value Patterns
  • URL Value Patterns
  • HTTP Value Patterns
  • Source Creation Patterns
  • Static Content Patterns
  • Source Lifecycle Patterns
  • TCP Patterns
  • UDP Patterns
  • TLS Client Patterns
  • TLS Server Patterns
  • HTTP Server Patterns
  • HTTP Client Patterns
• Options Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Definition Types
  • Result Types
  • Callback and Error Types
  • Pattern Definitions
  • Definition Construction Patterns
  • Definition Name Patterns
  • Definition Property Patterns
  • Parsing Patterns
  • Display Patterns
  • Result Patterns
  • Typed Value Access Patterns
• Path API Guidelines
  • Primary Types
  • Operation Types
  • Option Types
  • Value Types
  • Pattern Definitions
  • Path Value Patterns
  • Operation Accessor Patterns
  • Read and Write Patterns
  • Mutation and Temporary Resource Patterns
  • Information Patterns
  • Traversal Patterns
• Random Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Source Patterns
  • Selection Patterns
  • Build Patterns
  • Mutation Patterns
  • Construction Patterns
  • Application Patterns
• Regular Expression API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Pattern Definitions
  • Compilation and Matching Patterns
  • Match Result Patterns
  • Settings Patterns
  • Custom Input Patterns
• Stream API Guidelines
  • Core Semantics
    • Operation Model
    • Text and Sensitivity
  • Primary Types
  • Secondary Types
  • Pattern Definitions
  • Lifecycle Patterns
  • Positioning Patterns
  • Read Patterns
  • Write Patterns
  • Coroutine Patterns
  • Standard Stream Patterns
• System Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Lookup Patterns
  • Environment Variable Patterns
  • Process Information Patterns
  • System Information Patterns
  • Subprocess Patterns
  • Application Patterns
  • Platform Error Patterns
• Text Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Processing Types
  • Formatting and Parsing Types
  • Collection and Pattern Types
  • Document Types
  • Layout Renderer Types
  • Codec Types
  • Pattern Definitions
  • String Value Patterns
  • String Editing Patterns
  • Reader and Split Patterns
  • Conversion and Encoding Patterns
  • Formatting and Parsing Patterns
  • Sensitive UTF-8 Patterns
  • Document Patterns
  • JSON Value Patterns
  • Layout Renderer Patterns
  • Base-N Codec Patterns
  • Punycode and IDNA Patterns
• Time Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Amount and Part Types
  • Supporting Types
  • Policy Types
  • Part Value Patterns
  • Calendar Inspection Patterns
  • Civil Value Patterns
  • Time-of-Day Patterns
  • Duration and Delta Patterns
  • Date-Time Patterns
  • Time-Zone Patterns
  • Formatting and Parsing Patterns
  • Monotonic Time Patterns
• Unit and Value Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Concrete Unit Types
  • Value Types
  • Supporting Types
  • Pattern Definitions
  • Common Value Patterns
  • Index Patterns
  • Length and Offset Patterns
  • Range Patterns
  • Ratio Amount Patterns
  • Version Patterns
• Utilities API Guidelines
  • Primary Types
  • Secondary Types
  • Pattern Definitions
  • Hash Patterns
  • Common Container Patterns
  • List Patterns
  • Set Patterns
  • Map Patterns
  • Flag Patterns
  • Result Patterns
  • Coroutine Patterns