Effective Commenting

When to use

• Explaining complex business logic or algorithms.
• Documenting public APIs (Data layer → Domain layer).
• Clarifying non-obvious workarounds, hacks, or side effects.
• Warning about potential pitfalls or future refactoring needs.

Steps

1. Assess Necessity: Review if the code can explain itself; if so, proceed without comments. Only comment if the code cannot convey the full context.
2. Clarify via Naming: Rename methods and variables to describe their purpose explicitly.
3. Document Intent: Write comments that explain the "why" (business context, constraints) behind the implementation.
4. Finalize Output: Ensure only the active, necessary code remains, removing any temporary artifacts or disabled blocks.
5. Distinguish Scope: Use /// for public API documentation and // for internal implementation notes.

Code