Summary

Standardize the Result API by establishing member methods as the primary interface and deprecating free functions. Analysis shows member methods are used 5.6x more frequently than free functions (510 vs 91 usages).

Current State

Dual API Problem

The Result class provides two parallel APIs for the same operations:

Member Method API (Primary - 510 usages)

result.is_ok()      // 200 usages
result.value()      // 196 usages
result.error()      // 114 usages
result.is_err()
result.unwrap()
result.map(func)
result.and_then(func)

Free Function API (Secondary - 91 usages)

is_ok(result)       // Part of 91 total
get_value(result)
get_error(result)
is_error(result)
value_or(result, default)
map(result, func)
and_then(result, func)

Usage Analysis

Test File Inconsistency

Problem Analysis

Kent Beck Principles

• Reveals Intention: Single clear API is better
• Fewest Elements: One API style, not two

Proposed Solution

Phase 1: Documentation Standardization (Immediate)

• Update BEST_PRACTICES.md to recommend member methods
• Add clear guidance on when free functions are appropriate:
  • Generic templates requiring ADL
  • ASSIGN_OR_RETURN macro internals
  • Functional programming patterns
• Update code examples throughout documentation

Phase 2: Test Consistency (Short-term)

• Keep result_test.cpp as "free function contract tests"
• Ensure improved_result_test.cpp comprehensively covers member API
• Update integration tests to consistently use member methods
• Add clear test file naming/comments indicating API style tested

Phase 3: Deprecation (Medium-term)

• Add [[deprecated]] to free functions in utilities.h:

  [[deprecated("Use result.is_ok() instead")]]
  template<typename T>
  bool is_ok(const Result<T>& result);
  
  [[deprecated("Use result.value() instead")]]
  template<typename T>
  const T& get_value(const Result<T>& result);
  
  [[deprecated("Use result.error() instead")]]
  template<typename T>
  const error_info& get_error(const Result<T>& result);

• Update MIGRATION_GUIDE with deprecation timeline
• Add compiler warnings for deprecated usage

Phase 4: Removal (Long-term - 2+ major versions)

• Remove deprecated free functions
• Simplify utilities.h to contain only:
  • Factory functions: ok(), make_error()
  • Exception conversion: try_catch()
  • Convenience macros: COMMON_ASSIGN_OR_RETURN

Migration Guide

Free Function to Member Method Mapping

Code Migration Example

// Before (free function style)
if (is_ok(result)) {
    auto value = get_value(result);
    process(value);
} else {
    log_error(get_error(result));
}

// After (member method style)
if (result.is_ok()) {
    auto value = result.value();
    process(value);
} else {
    log_error(result.error());
}

Tasks

Immediate

• Update BEST_PRACTICES.md with API recommendation
• Add "Recommended API Style" section to result documentation
• Review and update code examples in docs/

Short-term

• Audit all internal code for API consistency
• Update integration tests to use member methods
• Add deprecation comments (not attributes yet) to free functions

Medium-term

• Add [[deprecated]] attributes to free functions
• Create migration guide document
• Update downstream systems (container, database, network, etc.)

Long-term

• Remove deprecated free functions (major version)
• Simplify utilities.h

Acceptance Criteria

• Documentation clearly recommends member methods
• BEST_PRACTICES.md updated with examples
• Test files have clear purpose annotations
• Free functions marked with deprecation comments
• No new code uses free functions (enforced in review)

Files to Modify

Related Issues

• [REFACTOR] Consolidate Result<T> headers from 9 to 3 - C++20 Module preparation #255 - Consolidate Result headers
• feat: Adopt C++20 Concepts for interface type constraints #244 - C++20 Concepts adoption