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
    • Common Rules
    • Regular Expressions
• 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
  • Teach Concepts Through Working Examples
    • Introduce the underlying concept before walking through the demo
    • Introduce the purpose of each operation before its architectural classification
    • Explain the normal execution path before discussing variations
    • Give each example one teaching purpose
    • Keep declarations that explain ownership and execution visible
    • Explain details in proportion to their role in the task
  • Section Titles That Help Readers Navigate
  • Review the Reader’s Path
  • Recommended Writing Style
  • Anti-Patterns
  • Related Guidelines
• Reference Page Guidelines
  • File Structure
  • Page Structure
  • Related Guidelines
• Maintenance Tool Documentation Guidelines
  • Choose the Destination
  • Write a Command Usage Page
  • Write Technical Reference Pages
  • Maintain Navigation and Boundaries
• Writing Style
  • General Guidelines
    • Topic Pages
• Guidelines for Writing Demos
  • Purpose of Demos
  • Demo Executable Behavior
  • Terminal Capture
  • Structured Demo Applications
  • Demo Code in Documentation Pages
  • Language and Themes in Demos
  • Code Style, API Usage and Theming
• Integrating Demos into Pages
  • Start with the Reader’s Task
  • Choose Source Lines
  • Capture Commands and Output
    • Inputs and Temporary Files
  • Synchronize and Review
• 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
    • API Documentation on Member Implementations
    • Misplaced Unit-Test Metadata
    • Missing Default Group Comment
    • Multiple Classes, Structs, or Enums in a Header
    • Regular Literal Strings for Erbsland Core APIs
    • Erbsland Core Containers Strict
    • Named Constant for Repeated Literals
    • Silencing nodiscard with static_cast<void>(...)
    • Inefficient and Unnecessary Conversions or Copies
    • Nested Namespace Blocks and End Comments
    • Multiple Distinct Namespaces in One Unit
    • Unnecessary Unit Conversions
    • Unnecessary Type Construction
    • Namespace Noise
• Archive Format Documentation
  • Specification Mapping
  • Security-Relevant Decisions
  • Path and Record Safety
  • Integrity and Resource Lifetime
• 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
  • Namespace Views
  • 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
• Compression Domain API Guidelines
  • Primary Types
  • Secondary Types
  • Archive Types
  • Archive Patterns
  • Byte Compression 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
  • Syntax Formatting Types
  • Pattern Definitions
  • Value Access Patterns
  • Document Construction Patterns
  • Parsing Patterns
  • Validation Rule Construction Patterns
  • Source and Trust Patterns
  • Syntax Formatting 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 and Parser Patterns
  • Protected Data Patterns
  • Key Agreement Patterns
  • Password Hashing Patterns
  • X.509 Certificate Patterns
  • Signature Verification Patterns
  • TLS 1.3 Record Protection Patterns
  • TLS Identity 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
  • Emulation and 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
  • Callback Binding Patterns
  • Subscription Patterns
  • Event Loop Patterns
  • Timer and Thread Patterns
  • Backend Patterns
  • Event Loop Options Patterns
• Internationalization API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Registry Patterns
  • Data Patterns
  • Translator Patterns
• Log Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Manager Patterns
  • Producer Patterns
  • Configuration Patterns
  • Writer Filter Patterns
  • Writer Patterns
  • Trace Section Validation 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
  • 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
  • Sequential Bit Read and Write Patterns
  • Ring Buffer 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
  • Path Glob 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
  • Cached Literal 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
  • Temporary File Commit Patterns
  • Coroutine Patterns
  • Standard Stream Patterns
• System Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Lookup Patterns
  • Environment Variable Patterns
  • PATH Access Patterns
  • Environment Change 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
  • Character Set Construction Patterns
  • String Value Patterns
  • String Joining Patterns
  • String Transformation 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
  • Placeholder Patterns
  • Named-Key Parsing Patterns
  • Base-N Codec Patterns
  • Punycode and IDNA Patterns
  • String Matching Patterns
  • C++ Source Scanning Patterns
• Data Domain API Guidelines
  • Core Semantics
  • Primary Types
  • Secondary Types
  • Value Patterns
  • XML 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
  • Timestamp 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
  • Cooperative Stop Types
  • Pattern Definitions
  • Hash Patterns
  • Common Container Patterns
  • List Patterns
  • Set Patterns
  • Map Patterns
  • Cache Patterns
  • Flag Patterns
  • Result Patterns
  • Coroutine Patterns
  • Cooperative Stop Patterns
  • Worker Pool Patterns
  • Utilities Frontend Patterns