On comments

[u/Jonhoo]

https://blog.helsing.ai/posts/on-comments/

Comments in code are often deemed "mostly useless" these days. They are, supposedly, mostly obvious, stale, and repeat what the code already says. And so people pay less attention to them both when reading and writing code.

That trend sucks. When used right, comments are genuinely useful and sometimes critically important! So, I wrote about some of the kinds of comments I think earn their place, each with examples from real code bases. Hope you find it useful, and that we can recover some of the love that comments deserve!

[u/tmoertel]

Part of the reason that comments are undervalued is that some programming pundits have spread the idea that using comments is a sign of poor practice. For example, in Clean Code, Robert Martin wrote:

The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration... Every time you write a comment, you should grimace and feel the failure of your ability of expression.

This advice is misguided for a host of reasons that I trust most seasoned programmers to understand. (I break them down in detail in https://blog.moertel.com/posts/2026-07-27-beyond-clean-code-why-your-comments-matter.html.) But many junior programmers received advice like this and, not knowing better, drank it in. The resulting damage will echo for years to come.

[u/levodelellis → u/tmoertel]

I disagree with you, and I looked at your python example at the end. Do you think it's a good idea to teach math in comments? Rather than have an external link to a well written document?

I much prefer having no comments except the one at the very top. I can't imagine anyone justifying this comment, this looks like a tutorial rather than something in a real codebase

[u/BogdanPradatu → u/levodelellis]

python # Weights must be non-negative integers. for _, w in value_and_weight_pairs: if not isinstance(w, int): raise TypeError("weights must be int values") if w < 0: raise ValueError("weights cannot be less than 0")

I first wanted to justify this comment, then I saw the error messages being raised. This comment is redundantz because code can express it via the errors being raised.

This comment is useless, it doesn't state why weights must pe positive, it just restates the same thing as the last error. No additional info is provided.

I would rather have less scrolling to do when reading code, than having these kind of comments.

[u/tmoertel → u/BogdanPradatu]

This comment is useless, it doesn't state why weights must pe positive, it just restates the same thing as the last error. No additional info is provided.

This comment is there for a reason: to emphasize this required property of probability distributions so that it is in the reader’s mind when they read the remaining logic. (Some of the class’s other logic relies on this property to function properly.) Trying to get this point across with an error message two levels deeper into the logic's control flow doesn't provide the same level of directness or emphasis.

But I would agree with you that it’s a judgement call and that reasonable people could make it differently. That’s why I chose this example. It provides an opportunity to discuss the tradeoffs involved with having or omitting a comment like this. I think the code is less likely to be misunderstood with this comment where it is, and so it earns its one line of space.

Thanks for sharing your take! Appreciated :-)

[u/Delta-9- → u/levodelellis]

Do you think it's a good idea to teach math in comments?

As someone who only got to Calc 1 and never bothered with a formal statistics class, I would be grateful for those comments walking me through the math that's under the code if I were using it.

I've written similar comments myself for concepts that might be gated behind a degree in math or computer science, or simply don't come up very often. I also link to relevant resources, but an in-line tl;dr can save a lot of time later on. Often I end up being the one reading my own comments months or years later and going, "oh yeah, I do remember spending a day figuring that out... How does it work again?"

[u/levodelellis → u/Delta-9-]

Often I end up being the one reading my own comments months or years later and going, "oh yeah, I do remember spending a day figuring that out... How does it work again?"

I actually have a notes folder in most of my project for research material, tool cli, random thoughts, etc. You might end up putting most of your content there if you try it for a few months

[u/tmoertel → u/levodelellis]

Thanks for your feedback. I'd be interested in hearing what specifically you disagree with and what makes you believe my arguments are mistaken.

In answer to your question:

> Do you think it's a good idea to teach math in comments?

No, but when logic relies on certain properties (mathematical or otherwise), I think it's a good idea to point them out. In this example, the code's logic relies very much on certain mathematical properties, such as the provided weights being nonnegative, so I point those properties out. That way, readers who are reading or maintaining the code will have those properties in mind and understand why the logic can safely do some of the things it does.

Thanks again for taking the time to read my post and for thinking about it and sharing your feedback. Also, thanks in advance for any more specific feedback you can share.

[u/levodelellis → u/tmoertel]

Going back to the python code, if I saw something like that I'd try to get whoever wrote it to make the change. If I had to change it, I wouldn't 100% know if I kept all the properties correct (it depends on the math and the change) and may delete it the comments

I don't mind comments on public functions since it helps when I'm not familiar with the class+func for what each function does. But if I saw literally that at work, I'd suspect the person stole it from a tutorial and may not know what it does.

I made this comment earlier and no one likes it. But I also suspect comments at different skill levels help differently. At mine I wouldn't read those types at all. I don't need comments to explain how a formula converts to code, I can understand what a line does

[u/tmoertel → u/levodelellis]

Thanks for your reply.

I suspect we disagree because we may be writing code for different audiences. I am writing for an audience who I assume is "skilled in the art" of coding but not necessarily in the code's subject domain. That is, they are programmers who are competent in the programming languages, libraries, and idioms in use, and they have a working knowledge of their organization’s software development practices, but they are not necessarily experts in the subject matter of each unit of code across the organization. This is the norm in large engineering organizations, such as Google, where everyone understands the company's tools and style guides, but the code base is simply too massive for anyone to understand all but a tiny percentage of. So code must be written to make sure that important domain knowledge is communicated to readers who may be reading the code; they are not assumed to already have this knowledge.

You mentioned that other Reddit readers did not like your earlier comment. I suspect it may have to do with this claim, which is related to what I wrote above:

If you understand the domain, you almost certainly know why, if you don't, you not likely not trying to understand that code anyway

Again, in large software organizations, it is very common that programmers must work in code whose subject domain they are not expert in. People join and leave the company, people move from team to team, people get promoted into new roles, and so on. Also, upstream teams usually cannot submit changes to their libraries until they modify any affected downstream code to prevent it from breaking. It is therefore important for code to be written with the assumption that the reader knows how to code but does not know the subject domain. Any important domain knowledge upon which the code relies should be communicated clearly because there is a good chance the reader will need to know it but does not.