4 ms·

What in your opinion is the benefit/difference of this, versus commenting nonobvious code? I tend to prefer the latter. Each time I work on someone else's cod

by axaxs 7y ago

What in your opinion is the benefit/difference of this, versus commenting nonobvious code? I tend to prefer the latter. Each time I work on someone else's code, I'm elated if they write longform comments about what they're doing or why. I think tracking down commit messages would be more cumbersome.

deanmoriarty 7y ago
I tend to put comments around VERY tricky pieces of code, but the rest belongs to the commit log. I feel code comments tend to rot because they are not as immutably bound to the code they describe as a commit message is, and for the most part my commit messages are too verbose to end up in code comments, it would create too much clutter. I have a good integration with my editor that shows inline blame annotations for the current line (and full message is a keystroke away).
pm215 7y ago
Good comments are important too. But comments describe the code as it is at this point in time ("why is the code doing X?"); commit messages describe the change ("why are we making the code do X rather than Y?"). Sometimes the same information should go in both places; but the focus and emphasis when you're writing the description up varies. A good commit message is also really useful for code reviewers: it sets the stage and contextualises all the code they're about to read.
- axaxs 7y ago
  Both good points to consider - thank you.
- mumblemumble 7y ago
  To add to that, probably at length: Some information is a pre-requisite for understanding a specific block of code. This information is a great fit for comments, because everyone who's looking at the code will need to know it, and having it in a comment ensures that it's discoverable. Other information is a pre-requisite for understanding the engineering or business decisions that motivated a design decision, but isn't necessary for understanding how the code works or how to interact with it. That makes it less appropriate for comments, because the comment would just be clutter (light pleasure reading at best) under the most typical use case. People who are engaging in those use cases should know how to use git blame to find what they need. For still others, the unit to which the information applies is not a block of code; it's a set of changes. In those cases, comments are a terrible choice for conveying that information. Maybe a commit message is better. If it's not, you probably need to be looking to a project wiki or some separate documentation files, so that the information can be written and maintained in one place. You can still use comments, but they should merely cross-reference the centralized documentation. Today's copy/paste is tomorrow's outdated and misleading misinformation.
IE6 7y ago
In my experience I don't see them as mutually exclusive. Good comments in code should still be in place. In my opinion the git history should not explain what the code does necessarily but instead the nature of the changes that were made. In my experience projects are significantly easier to manage if commits are squashed into larger commits that have (1) a clear title, (2) clear summary of what was done, and (3) some link to the tickets in JIRA with the full details. In the short term it may not make a big difference but once you have years of history in a single project as well as many hotfixes or releases the better organization of git makes the project easier to manage.
mannykannot 7y ago
When a straightforward piece of code is replaced by another, it can still be useful to know why. Being able to seamlessly browse the history of a given function is one of the things a fully integrated development environment should support.

by axaxs 7y ago

deanmoriarty 7y ago

I tend to put comments around VERY tricky pieces of code, but the rest belongs to the commit log. I feel code comments tend to rot because they are not as immutably bound to the code they describe as a commit message is, and for the most part my commit messages are too verbose to end up in code comments, it would create too much clutter. I have a good integration with my editor that shows inline blame annotations for the current line (and full message is a keystroke away).

pm215 7y ago

Good comments are important too. But comments describe the code as it is at this point in time ("why is the code doing X?"); commit messages describe the change ("why are we making the code do X rather than Y?"). Sometimes the same information should go in both places; but the focus and emphasis when you're writing the description up varies. A good commit message is also really useful for code reviewers: it sets the stage and contextualises all the code they're about to read.

axaxs 7y ago
Both good points to consider - thank you.
mumblemumble 7y ago
To add to that, probably at length: Some information is a pre-requisite for understanding a specific block of code. This information is a great fit for comments, because everyone who's looking at the code will need to know it, and having it in a comment ensures that it's discoverable. Other information is a pre-requisite for understanding the engineering or business decisions that motivated a design decision, but isn't necessary for understanding how the code works or how to interact with it. That makes it less appropriate for comments, because the comment would just be clutter (light pleasure reading at best) under the most typical use case. People who are engaging in those use cases should know how to use git blame to find what they need. For still others, the unit to which the information applies is not a block of code; it's a set of changes. In those cases, comments are a terrible choice for conveying that information. Maybe a commit message is better. If it's not, you probably need to be looking to a project wiki or some separate documentation files, so that the information can be written and maintained in one place. You can still use comments, but they should merely cross-reference the centralized documentation. Today's copy/paste is tomorrow's outdated and misleading misinformation.

IE6 7y ago

In my experience I don't see them as mutually exclusive. Good comments in code should still be in place. In my opinion the git history should not explain what the code does necessarily but instead the nature of the changes that were made. In my experience projects are significantly easier to manage if commits are squashed into larger commits that have (1) a clear title, (2) clear summary of what was done, and (3) some link to the tickets in JIRA with the full details. In the short term it may not make a big difference but once you have years of history in a single project as well as many hotfixes or releases the better organization of git makes the project easier to manage.

mannykannot 7y ago

When a straightforward piece of code is replaced by another, it can still be useful to know why. Being able to seamlessly browse the history of a given function is one of the things a fully integrated development environment should support.