3 ms·

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 tha

by tmh88j 6y ago

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?

nemetroid 6y ago
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! :)
- tmh88j 6y ago
  >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.
  - nemetroid 6y ago
    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.

by tmh88j 6y ago

nemetroid 6y ago

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! :)

tmh88j 6y ago
>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.
- nemetroid 6y ago
  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.