code-comments

Inline code comments should be co-located with the source they describe to prevent drift. Focus on explaining the why behind architectural decisions and complex logic rather than just stating what the code does.

Co-located documentation is the best way to prevent drift, keeping explanations directly within the source files. This ensures that inline comments and architectural notes live alongside the code they describe for future readers.

Yes, co-located comments can be applied across languages like TypeScript, Swift, and Python. They conform to language-specific documentation patterns to effectively document functions, modules, and API boundaries.

Code comments should focus on the why because explaining decisions aids future readers and AI copilots in understanding intent. Documenting why a decision was made provides context that reading the code alone cannot convey.

You need inline comments for API boundaries and modules when complex logic or architectural decisions require explanation. Co-located documentation ensures these explanations remain with the source files to aid future maintenance.

To start adding inline comments, apply clear and actionable documentation to a sample function that illustrates its intent and edge cases. Ensure the comments are co-located with the code to explain the reasoning behind the logic.