Writing Comments in Programming

As a 23-year-old at the time of writing, I have had my fair share of moments grappling with programming. When I started, my understanding was straightforward but somewhat naive:

• I hadn't yet gained real-world experience in my domain.
• I struggled to distinguish the standards for including comments and knowing if they were succinct.
• I believed every code snippet should include comments to help readers understand the code's context and purpose.

However, through a couple of years working on various projects and engaging with extensive codebases, I've learned that the quantity and quality of comments aren't always correlated. Poor comments can be worse than none.

So, how do we decide when and what to include in comments to make them effective?

As Peter Vogel has written:

• Writing and maintaining comments is costly.
• Compilers don't check comments, so there's no guarantee they're correct.
• The computer will always do what the code specifies, regardless of comments.

This suggests it's often better to "tell" the compiler, and people potentially, through clear and expressive code rather than rely on comments. Here's an example to illustrate this:

if (userRole === 'member') {
    // Show member-only content
    document.getElementById('member-content').style.display = 'block';
    // Hide admin-only content
    document.getElementById('admin-content').style.display = 'none';
} else if (userRole === 'admin') {
    // Show admin-only content
    document.getElementById('admin-content').style.display = 'block';
    // Hide member-only content
    document.getElementById('member-content').style.display = 'none';
} else {
    // Show default content for non-logged-in users
    document.getElementById('default-content').style.display = 'block';
    // Hide member and admin content
    document.getElementById('member-content').style.display = 'none';
    document.getElementById('admin-content').style.display = 'none';
}
                

Compare that to:

if (userRole === 'member') {
    document.getElementById('member-content').style.display = 'block';
    document.getElementById('admin-content').style.display = 'none';
} else if (userRole === 'admin') {
    document.getElementById('admin-content').style.display = 'block';
    document.getElementById('member-content').style.display = 'none';
} else {
    document.getElementById('default-content').style.display = 'block';
    document.getElementById('member-content').style.display = 'none';
    document.getElementById('admin-content').style.display = 'none';
}
                

The above example suggest that, we can do both. Both as in both quality code, and expressive comments.

But that takes me back right to Peter Vogel's three statements at the start. Compilers will do exactly what you want as time goes on (considering you are updating the codebase). We can have pipelines, test cases, compiler checks, … Comments are not often get updated, on the other hand, and does not have these kind of checks (maybe AI will).

Comments are still useful though. Like this example with referencing math or algorithm:

par = PassiveAggressiveRegressor().fit(x_train, y_train)
# taken from https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.PassiveAggressiveRegressor.html
                

Comments can also be useful for:

• Documenting performance optimizations.
• Referencing other external resources or documentation.
• Pointing bugs or explaining fixes.
• Enhancing readability in complex sections.

Good code combined with meaningful comments can save time and reduce frustration for you and your teammates. Although coding philosophies may vary, and some prefer detailed comments while others lean towards self-explanatory code, a balanced approach often works best. While I still believe comments can provide valuable context, I've learned that clear code can often express intent more effectively than comments alone.