Inline Documentation for Complex Logic
What you'll learn: How to use inline comments strategically to explain why your code does something unusual, complex, or non-obvious.
The Core Idea
Not all code needs comments—simple, well-named functions and variables speak for themselves. But when you implement a complex algorithm, encode a specific business rule, or apply a workaround for a known bug, inline comments become essential guideposts for future maintainers (including yourself three months from now).
Think of inline comments like margin notes in a textbook: you don't annotate every sentence, just the tricky theorems and proofs that require extra context.
What Deserves Inline Documentation
Complex algorithms: If you're implementing binary search, a sorting optimization, or any non-trivial logic, explain the approach in a brief comment before the block.
Business rules: When code enforces a specific policy ("customers over 65 get automatic discounts"), document it. The what might be clear from the code, but the why this specific rule exists often isn't.
Workarounds and gotchas: If you're working around a third-party library bug, browser quirk, or platform limitation, document it thoroughly. Include ticket numbers or links when applicable. Future developers need to know whether they can remove this hack or if it's still necessary.
Non-obvious optimizations: If you chose a less-readable approach for performance reasons, say so and explain the trade-off.
Keep Them Current
The worst comment is one that lies because the code changed but the comment didn't. When you refactor, update or remove outdated inline comments immediately.
Key Takeaway: Use inline comments sparingly to explain why complex logic exists, document business rules, and warn about workarounds—but never as a substitute for clear code structure and naming.