4 ms·

>Too many people think that commit message is to explain HOW you did something. >WHY you did it this way is the most important part. What was done is better s

by tmh88j 6y ago

>Too many people think that commit message is to explain HOW you did something. >WHY you did it this way is the most important part. What was done is better suited for the commit message than how and why it was done, in my opinion. The latter two are better explained by comments in the code. I agree that why something was done is important for future reference, but when I'm tracking down code changes I'm looking for hints of the change itself. Understanding why comes next once you have the commented code in front of you to reference.

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

by tmh88j 6y ago

rootusrootus 6y ago

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

nemetroid 6y ago

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.

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