Code Documentation Style

Self-documenting code comments explain the rationale and high-level design decisions behind complex logic rather than describing surface behavior. Focus on intent and architectural decisions to help future readers understand why the code exists.

The best way to comment complex algorithms for maintainability is adding evergreen, rationale-focused comments. Frame non-obvious calculations and edge cases by referencing architectural decisions and high-level design intent rather than surface behavior.

Add comments to code architecture when dealing with complex functions, tricky algorithms, and non-obvious design decisions. Comments should provide framing for edge cases and explain why specific architectural choices were made to improve project maintainability.

Avoid writing time-bound code comments by crafting evergreen, minimal comments that focus on high-level rationale. Ensure comments remain accurate as code evolves by avoiding noise and temporary notes that lose relevance over time.

Describing what code does focuses on surface behavior, while explaining code rationale focuses on intent and high-level design decisions. Self-documenting code requires comments that reference why decisions were made to improve long-term maintainability.