On writing comments in code

As a 23-year-old at the time of writing, I'd had my fair share of moments grappling with programming. When I started out, 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 context and purpose.

A couple of years working on various projects and engaging with sprawling codebases later, 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?

The case against comments

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, secondarily — through clear and expressive code, rather than rely on comments. Compare:

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';
}

And the same logic without the running narration:

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';
}

You could argue we can do both: keep both quality code and expressive comments. But that takes me back to Vogel's three statements. The compiler will do exactly what you want as time goes on (assuming you keep updating the codebase). We have pipelines, tests, type-checkers — all kinds of guards. Comments don't have those guards. They're free to drift, and they usually do (maybe AI will help one day).

When comments do earn their keep

Comments are still useful — like attaching the source of a math reference or algorithm:

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

Comments also pull weight when they're:

• Documenting performance optimizations the code can't explain on its own.
• Referencing external resources, papers, or documentation.
• Pointing at known bugs or explaining a non-obvious fix.
• Sketching the shape of an unusually complex section before the reader dives in.

A balanced approach

Good code combined with meaningful comments saves time and reduces frustration — for you and for whoever reads it next. Coding philosophies vary; some prefer detailed comments, others lean toward self-explanatory code. A balanced approach usually wins.

I still believe comments can carry valuable context. I've also learned that clear code expresses intent more effectively than comments alone — and that the best comment is often the one you didn't have to write because the code already said it.