The Art of Commenting: When, Where and Why

In my first job, on third or fourth day, while getting taught about the best practices, Pratik, who was senior software engineer at that time, mentioned that code should be like a poem: flowing, easy to understand and tells a story. Those lines stuck with me.

This poetic approach to coding highlights an essentials in software developement. Writing clean, efficient code is only half the battle. The other half? knowing when and how to document your code effectively. This guide will walk you through the best practices for code commenting that I have gathered over the years.

When to write comments: Illuminating the dark corners of your code:

1. Explaining complex logic or algorithm:

When you are implmenting complicated or hard logic/algorithm that isn't immediately apparent, comments can serve as a road for other developers (including your future self).

2.Explaining non-obvious design descisions:

Sometimes, the reasoning behind a particular implementaion isn't clean form the code alone. Use comments to shed light on these descisions.

3. Documenting functions and methods:

Provide clear documentation for the purpose, parameter, and return values of functions and methods. This practice is especially crucial for APIs and libraries.

4. Clarifying workarounds and temporary solutions:

If you've implemented a quick fix or a workaround, leave a comment explaning why it was necessary and future plans for a more permanent solution.

When to avoid comments: Letting your code speak for yourself

1. Stating the obvious:

Avoid comments that merely restate what the code is clearly doing.

2. Redundant explanation:

If your code is clear and self-explanatory, additional comments can actually decrease readability.

3. Commenting out old code:

Instead of leaving large blocks of commented-out code, use version control system to track changes and remove the commented code.

4. Excusing poor code quality:

Comments should not be used to justify poorly written or inefficient code. Instead, refactor the code to make it clearer.

Where to place comments

1. File headers:

Use file-level comments to provide an overview of the file's content, purpose, and any relevant information/metadata.

2. Before classes and functions:

Use docstrings or similar conventions to document the purpose, parameter, and return values of classes and functions.

3. Inline for complex code:

Place comments next to particularly complex or non-obvious lines of code to explan the logic.

Mastering the art of code, commenting is about finding the right balance. Your goal should be to write code that is so clear and self-explanatory that it needs minimal commenting. However, when comments are necessary, they should provide genuine value, offering insights that the code alone cannot convey.

Remember, the best code tells a story and sometimes, well-places comments are the perfect narration to that story.

🦦