[huggyface]

After the recent discussion about code-comments, that sort of code is exactly the sort that requires an explanatory comment.

If the code isn't the clearest comment you have, you're doing it wrong.

Comments are a crutch for people who write poor code. Comments have zero authority or guarantee of accuracy, and more often than not have little correlation with the actual code.

Code is canonical. Comments are noise.

[joshhart]

I think you're wrong for one simple reason: business logic.

Business logic is complicated and rarely defined by a developer but by a product manager. Often you can understand what's being done in the code, but the WHY is necessary to understand why it's there and what it is trying to do. I believe giving a brief synopsis of the business logic in a method comment and, if it's not super straightforward, a brief overview of the steps or algorithm, is incredibly useful.

I guarantee you won't be able to figure out what your program is doing by looking through years old wikis left by product managers no longer at your company.

[huggyface]

Just to be clear, the person I responded said, in effect, that the code did X. They made code that did Y, and then realized it didn't do X. That is the story of a million ill conceived code rewrites.

That the code did X is clear by the code: No amount of words can refute or change that the code does X. The danger is replacing code is always in the behavior of the code, and never simplified descriptions of its actions.

To business logic, as someone who has worked heavily with business code for years (laughable commentary from imbeciles to the contrary), business logic in comments is one of the worst choices a team can make because it is an escape hatch. It negates the need for verbose, traceable code. It negates the need for vastly superior external proof.

[eru]

Mathematicians have much more convenient symbols and powerful notation than programmers. Yet they use text, too. Even wondered why?

Donald Knuth, who gives money to people who spot bugs in his code, even invented literate programming to mix prose explanation and code better. Is he an idiot?

[huggyface]

I'll happily be "so brave" and reiterate a simple truism of software development -- comments are the battle cry of terrible developers.

They are the crutch of people who can't read code: "Add more comments because otherwise I can't make sense of what the statements are doing." It is the English speaker demanding that every French passage have an English translation, rather than simply learning French.

They are the crutch of people who can't write code. "My code is a gigantic, illiterate mess, so instead read the comment at the top that has no guarantee of being robust or accurate."

Bringing up mathematicians and Knuth are both irrelevant distractions. Software development in the modern world is a very structure, self-describing affair, or at least it should be. Comments are the short-circuit from having to figure out how to do that.

[wtetzner]

You seem to be missing the point of comments. Comments are not meant to explain what your code does. They are for explaining why.