Requirements change over time, and so do the "why"s. So unless the code base is your primary documentation for requirements, "why" comments in the code can be dangerous: while outdated "what" comments can be determined as such by reading the code, there is no way (from the code itself) to determine whether a "why" comment is still accurate.

A "why" comment in a commit message, on the other hand, only tells you what the "why" was at that time, something that cannot become outdated.

>So unless the code base is your primary documentation for requirements, "why" comments in the code can be dangerous

No, but you seem to be implying that commit messages serve that purpose. If your code changes why wouldn't you add new comments and remove outdated/misleading comments?

>A "why" comment in a commit message, on the other hand, only tells you what the "why" was at that time, something that cannot become outdated.

What is version control for if not to retain state of the code as it was being written? Any popular IDE has simple interfaces to compare commits and see what was changed.

> If your code changes why would you leave outdated and misleading comments?

The point is that the code might not change. When you wrote it, maybe it was to cover use cases A and B. Sometime later, a new use case ”C” is added to the requirements, and this particular part of the code happens to already support C without making any changes.

Now, further down the line, some developer comes along to work on this code. If there’s a comment saying ”this code was written to support use cases A and B”, the developer will likely not take C into consideration when making their changes, and risk subtly breaking things.

You seem to be confusing end user documentation with code documentation....an actual document that describes how to use the software vs comments in the code that describes how it works

>Sometime later, a new use case ”C” is added to the requirements, and this particular part of the code happens to already support C without making any changes.

Can you give an example of a new use case being introduced without the code changing? Why would this be documented in the code in the first place if nothing has changed?

I’m not confusing anything, but I’m using the term ”use case” in a very broad sense.

> Can you give an example of a new use case being introduced without the code changing?

I once wrote a framework for processing data in different proprietary formats from different vendors into a unified format. At first, each vendor had its own code module, and any idiosyncrasies between different data files for a given vendor were solved within that module.

However, later on, we had to split one vendor into two modules. Now, some key parts of the code had to be changed to account for this, as it could no longer be assumed that one module would handle one vendor. But most parts of the code was already abstracted over the modules, and didn’t care.

> Why would this be documented in the code in the first place if nothing has changed?

That’s what I’m asking you! :)

>That’s what I’m asking you! :)

As I've been saying comments in the code should describe how that specific section of code works, and why it's done that way if the "how" isn't enough. The new parts of the codebase would have comments describing how that code works. The unchanged code still functions as it always did. There's no reason to make comments on how another part of the codebase works. Code comments shouldn't be architectural descriptions of an entire codebase.

Then perhaps we have different definitions of what "why" comments are. The usual reason we write code is to solve (business) problems, so to me, "why" implies a connection to business requirements. So even though

> The unchanged code still functions as it always did.

...the why of that unchanged code, i.e. the reason it exists at all, may change. And for that reason, the "why" (the business reasons) should not be in the code.

> The latter two are better explained by comments in the code

Totally agree. Commit metadata is nice to have, but ultimately I think good code mostly explains "how" by the code itself, and "why" should be comments. Especially for local context, where the why has to do with some other bit of code. Individual commit messages are also secondary to the pull request merge commit, which should have a better explanation of the goal, or tie it to a task, etc.