Inline Documentation & Clean Code

Code should be written for human readers first and computers second.

Self-Documenting Code

The best documentation is code that reveals its intent without comments:

• Descriptive Names: calculate_interest_rate() instead of cir().
• Small Functions: Break complex logic into smaller, well-named pieces.
• Explain with Code: is_valid_user = user.active and not user.banned instead of a comment explaining the if condition.

When to Comment

• Explain WHY, not WHAT: Don't comment what the code does; explain the non-obvious rationale behind it.
• Legal/Attribution: For licenses or inherited complex algorithms.
• Warnings: "Don't change this order, it will break [Service X]".
• TODOs: Tracking debt or future work (but keep these to a minimum).