Comments - Do you follow the code commenting standards?

There is almost always a better alternative to adding comments to your code.

What are the downsides of comments? What are the alternatives? What are bad and good types of comments?

There is almost always a better alternative to adding comments to your code. Chapter 4: Comments, Clean Code is a treatise par excellence on the topic.

What are the downsides of comments?

1. Comments don't participate in refactoring and therefore get out of date surprisingly quickly.
2. Comments are dismissed by the compiler (except in weird languages like java) and therefore don't participate in the design.
3. Unless strategically added, they place a burden on the reader of the code (they now have to understand 2 things: the code and your comments).

What are the alternatives to comments?

1. Change name of the element (class, function, parameter, variable, test etc.) to a longer more apt name to further document it
2. For ‘cryptic’ code (perhaps to optimize it), rewrite it in simpler terms (leave optimization to the runtimes)
3. Add targeted unit tests to document a piece of code
4. Innovative techniques that are well known solutions to common code smells e.g.:
   • For large methods/classes, break them and have longer names for them
   • For a method with large number of parameters, wrap them all up in a Parameter Object
   • Pair up with someone else, think... be creative

What are some bad comments?

1. Those that explain the "what"/"how" of the code. Basically the code rewritten in your mother tongue
2. Those that documentation comments in non-public surface area
3. Commenting out the code itself (perhaps to work on it later? That’s what source control is for)
4. TODO comments (Little ones are OK, don't leave them there for too long. The big effort TODOs - say that are over an hour or two - should have a work item URL to it) And many more...

What are some good comments?

1. Comments that explain the why (e.g. strategic insights)
2. ...that hyperlink to an external source where you got the idea/piece of code
3. ...that hyperlink to a Bug/PBI for adding some context
4. ...that are documentation comments for your next-biggest-thing-on-Nuget library
5. ...that are real apologies (perhaps you had to add some gut-wrenching nasty code just to meeting time constraints, must be accompanied by a link to Bug/PBI)

The one-year test

A good comment explains something that stays true and is not visible in the code: what a sentinel value means, an invariant, why a value must never change. A bad comment narrates the change that produced the current state, or restates what is on the line. Once the change settles, the second kind reads as stale clutter.

AI coding agents are especially prone to the second kind. They tend to narrate the diff they just made, so review their comments with this test: would this comment still earn its place a year from now, with the change long forgotten?

public enum OrderSource
{
    // Renamed from LegacyChannel in the March refactor. Kept the same numbers
    // so the refactor did not need a data migration.
    Workflow = 1,
    Import = 2,
    Api = 3,
}

❌ Bad example - This narrates the refactor that produced the code. Once it ships, nobody asks what the enum used to be called

public enum OrderSource
{
    // 0 is a sentinel meaning the source was never set. New code never writes it.
    // These values are persisted in Orders.Source, so never renumber them.
    Unknown = 0,
    Workflow = 1,
    Import = 2,
    Api = 3,
}

✅ Good example - The meaning of 0 and the "never renumber" invariant are written down in the one place a maintainer will look, and both stay true next year

Last but not the least, some parting words from @UncleBob himself:

"A comment is an apology for not choosing a more clear name, or a more reasonable set of parameters, or for the failure to use explanatory variables and explanatory functions. Apologies for making the code unmaintainable, apologies for not using well-known algorithms, apologies for writing 'clever' code, apologies for not having a good version control system, apologies for not having finished the job of writing the code, or for leaving vulnerabilities or flaws in the code, apologies for hand-optimizing C code in ugly ways."
* Uncle Bob (Robert Martin of 'Clean Code' fame)