> 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.