Comment by nunez
1 month ago
I find it funny that we, collectively, are now okay with comments in the code.
I remember the general consensus on this _not even two years ago_ being that the code should speak for itself and that comments harm more than help.
This matters less when agentic tools are doing the maintenance, I suppose, but the backslide in this practice is interesting.
It's never been the consensus. As far back as I can remember, the wisdom was always to comment why the code does what it does if needed, and to avoid saying what the code does.
Saying that function "getUserByName" fetches a user by name is redundant. Saying that a certain method is called because of a quirk in a legacy system is important.
I regularly implement financial calculations. Not only do I leave comments everywhere, I tend to create a markdown file next to the function, to summarise and explain the context around the calculation. Just plain english, what it's supposed to do, the high level steps, etc.
> I remember the general consensus on this _not even two years ago_ being that the code should speak for itself and that comments harm more than help.
If that was the consensus, it was wrong. There are valuable kinds of comments (whys, warnings, etc) that code can never say.
I'd describe that as a trend, rather than a consensus.
It wasn't an entirely bad idea, because comments carry a high maintenance cost. They usually need to be rewritten when nearby code is edited, and they sometimes need to be rewritten when remote code is edited - a form of coupling which can't be checked by the compiler. It's easy to squander this high cost by writing comments which are more noise than signal.
However, there's plenty of useful information which can only be communicated using prose. "Avoid unnecessary comments" is a very good suggestion, but I think a lot of people over-corrected, distorting the message into "never write comments" or "comments are a code smell".
In context of the thread, that's because AI fixes the key problem with comments, because it maintains them when the code is updated.
yeah that was weird, it was like a cult and some coworkers of mine were religiously hunting down every comment in other people's MR's, just kinda assumed that "no comments" is a hard rule. Very strange, i had to fight many battles for my sanity. There are many cases where you may want to explain why this is coded the way this is coded, not just how.