Summary

Split large header files (result.h at 913 lines, error_info related headers) into smaller, focused modules to improve compilation times, maintainability, and code navigation.

5W1H Specification

• Who: common_system maintainers
• What: Decompose large monolithic headers into logical sub-headers
• Where: include/kcenon/common/patterns/ and include/kcenon/common/types/
• When: Before v0.3.0.0 (recommended for next major refactoring cycle)
• Why:
  • result.h is 913 lines - exceeds recommended 500 lines per header
  • Compile time increases with header size due to template instantiation
  • Code navigation and understanding is harder in large files
  • Difficult to identify which components are needed by consumers
• How: Extract logical units into separate headers with a master umbrella header

Priority

MEDIUM - Does not block functionality but impacts developer experience and build performance.

Current State Analysis

result.h (913 lines)

Proposed Directory Structure

include/kcenon/common/patterns/
├── result.h                      # Umbrella header (backward compatible)
└── result/
    ├── fwd.h                     # Forward declarations
    ├── error_info.h              # error_info struct and error codes
    ├── error_category.h          # Error category extensions
    ├── result_core.h             # Result<T> class definition
    ├── result_ops.h              # map(), and_then(), or_else()
    ├── result_helpers.h          # make_result(), make_error()
    ├── result_macros.h           # COMMON_RETURN_IF_ERROR, etc.
    ├── void_result.h             # VoidResult typedef
    ├── result_format.h           # std::formatter specialization
    └── exception_conversion.h    # try_catch, try_catch_void

Backward Compatibility Strategy

Phase 1: Split with Umbrella (Non-breaking)

// result.h - becomes umbrella header
#pragma once

#include "result/fwd.h"
#include "result/error_info.h"
#include "result/error_category.h"
#include "result/result_core.h"
#include "result/result_ops.h"
#include "result/result_helpers.h"
#include "result/result_macros.h"
#include "result/void_result.h"
#include "result/result_format.h"
#include "result/exception_conversion.h"

// Backward compatibility: all includes work via umbrella

Phase 2: Selective Import (Optional optimization)

// Consumer can choose fine-grained includes for faster builds
#include <kcenon/common/patterns/result/result_core.h>
#include <kcenon/common/patterns/result/result_ops.h>
// Skip formatting and macros if not needed

Tasks

Phase 1: Header Split (Priority)

• Create result/ subdirectory structure
• Extract error_info.h with error_info struct and error codes
• Extract error_category.h with error category extensions
• Extract result_core.h with Result class definition
• Extract result_ops.h with monadic operations (map, and_then, or_else)
• Extract result_helpers.h with factory functions
• Extract result_macros.h with helper macros
• Extract void_result.h with VoidResult typedef
• Extract result_format.h with std::formatter specialization
• Extract exception_conversion.h with try_catch utilities
• Create fwd.h with forward declarations
• Update result.h to be umbrella header
• Update all internal includes to use new paths

Phase 2: Testing

• Verify all existing tests pass
• Add include-what-you-use validation
• Measure compile time before/after
• Test backward compatibility with downstream systems

Phase 3: Documentation

• Update README with new header structure
• Add migration guide for fine-grained includes
• Document recommended include patterns

Acceptance Criteria

• Each new header is self-contained (compiles independently)
• Existing #include <kcenon/common/patterns/result.h> works unchanged
• No circular dependencies between sub-headers
• Each sub-header is under 300 lines
• Compile time reduction of at least 10% for partial includes
• All 100+ existing tests pass
• ThreadSanitizer and AddressSanitizer clean

Performance Targets

Downstream Impact

Risk Mitigation

• Breaking changes: Umbrella header ensures full backward compatibility
• Include order: Use include guards and forward declarations
• Circular deps: Design with clear dependency direction (fwd → core → ops → helpers)

Related Issues

• container_system: Similar refactoring needed for container.h (910 lines)
• Cross-system: Part of unified_system code quality improvement initiative