4 ms·

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

by tmh88j 6y ago

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

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

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

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.