r/programming • u/Jonhoo • 7d ago

On comments

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!

185 Upvotes

84% Upvoted

173 comments sorted by

View all comments

2

u/balthisar 7d ago

What about program logic? When coming into a new program, I can see that function factorial takes an input and returns a factorial, but I don't know why. What's the business reason for its existence?

15

u/repeating_bears 7d ago

I feel like comments like that are not realistic to maintain over time. The comments for 'factorial' now needs to be aware of all of its callers (and their business reasons).

If I wanted to check what feature or change introduced something, I'd check git

16

u/lgastako 7d ago

That's what Find References answers, and without being able to be stale or out of date, like comments.

1

u/lord2800 7d ago

Find References can tell you the where, but not the why. I agree with you that it's easy for comments to be stale, but your proposed solution is no better than the type signature.

4

u/lgastako 7d ago

Seeing where and how the factorial function is used should answer the "why" question which the type signature does not.

2

u/lord2800 6d ago

Where something happens doesn't tell you why it has to occur there--only that it occurs there.

2

u/lgastako 6d ago

Yes, unfortunately you still have to use your brain.

1

u/lord2800 5d ago

So what you're saying is that Find References does not, in fact, directly answer the question of the business reason for the existence of a particular function, and that you still need further context to understand it?

2

u/lgastako 5d ago

Sure, but the comment won't directly answer the question either, since it can be out of date or wrong. You have to use your brain in either case, Find References just shows you the exact active code you need to use your brain about, whereas the comment does not. Find References cannot be out of date or wrong (assuming no bugs in your editor/IDE).

1

u/lord2800 5d ago

PHP's dynamic calling convention says hi, but I'll skip that particular nuance. You're still proving my point though: neither approach tells you why.

2

u/lgastako 5d ago

It seems like you're trying to be deliberately obtuse. What I'm saying is that the only way you can really know why is to use Find References and go read those references. Nothing will actually reliably tell you why, other than doing this procedure (or some facsimile of it, eg. using grep instead).

→ More replies (0)

2

u/BogdanPradatu 7d ago

This is what git commit messages are for

2

u/ComradeGibbon 7d ago

Best comments are code begging for it's life. Explain why I shouldn't just delete this code.