Is it really that hard to write sensible comments? Well, after a few decades writing software, I've come to the conclusion that yes, yes it is. But just becaus

Is it really that hard to write sensible comments? Well, after a few decades writing software, I've come to the conclusion that yes, yes it is. But just because it can be hard to write a good comment it doesn't mean you need to agonise over it. Here are a few "simple" examples: // Once we receive the cancellation ack, we should automatically send the updated flow if (releasedFlow.Status == ReleasedFlowStatus.IndicativeCancelled) { await _mediator.Send(new SendFlowCommand ... It should be pretty clear from the context that that's what is happening and it doesn't explain why. This is because it would take multiple paragraphs to explain. Could I just post a link to the documentation about this business rule? Yes, but the location of the said documentation changes so often it can render the comment useless. Could I change it to say something like "Please refer to the documentation"? Sure, but then why don't I put that comment behind every piece of business logic? No, the simple purpose of this comment is just that - a comment on what the business rule was at the time of writing, especially with respect to the other possibilities. You can spend ages overthinking this but there's no point. Just read, understand and move on. What about this: if (foo) { DoFoo(); } else if (bar) { DoBar(); } else { // Intentionally empty } Dead code with a comment that explains nothing. Is this code better with or without the dead code and comment? I'd argue that the code is better with it. In fact, this is a well-known technique: https://en.wikipedia.org/wiki/Intentionally_blank_page https://en.wikipedia.org/wiki/Intentionally_blank_page Yes, you can argue that the coder should explain why it's blank. But this depends on the context, and who the intended audience is. Again, no need to overthink it. Read it, modify it if you really think it's necessary (keeping in mind that the alternative is often no comment or empty else statement), and move on with your life.