5 ms·

On the topic of "who wrote this shit", I'd really like to plug the idea that some of the most high-impact documentation you can write is a good commit message.

by Yen 5y ago

On the topic of "who wrote this shit", I'd really like to plug the idea that some of the most high-impact documentation you can write is a good commit message. Say you track down a bug, find a line of code that makes no sense, and `git blame` it, to discover that you wrote it yourself, 2 years ago. If the commit message is "bugfix flaky builds", good luck figuring it out. If the commit subject rather, is "bugfix flaky builds", followed by a message that explains what the flakiness was, why you think the change will fix it, what other bugs or limitations you were working around, and what upstream changes you might be waiting on that prevented further work, you're in a much better position. Suddenly you have a lot more context on what you were doing, why you were doing it, why you didn't do it better at the time, and in some cases it can even catch you from making an obvious but subtly-wrong mis-step. Similarly, if someone's confused by your code during code review, that's a great opportunity for either in-line comments, or commit messages, as appropriate. Unlike PR discussions, tickets, emails, slack threads, wiki pages, or photos of whiteboards, commit messages + git blame has an uncanny ability to be exactly the documentation you need exactly when you need it. Good git history practice can be one of the highest returning investments.

lostcolony 5y ago
Eh, I'm not sure I agree. What has gotten me the most value is having either the branch or the commit message tie back to a ticket somewhere. -That- has the original bug, the comment thread that led to the decision around why this particular fix, any additional comments around tradeoffs we were aware of, and what other options we dispensed with, etc. A well written commit message might explain what the issue was, but it won't have anywhere near the context the ticket and resulting comment thread should have.
- V-2 5y ago
  These two aren't mutually exclusive. Tickets, however, have lower long-term survivability (in my experience). Outsourcing, migrations, there are many scenarios in which the original tickets become inaccessible over time - and some codebases do last for years and years. Meanwhile the repository content (and thus the complete version history) usually survives as-is.
  - wruza 5y ago
    The commit message idea always felt a little strange/off to me. It's a string that you can't (generally) fix/extend later for those who may seek this information. Also nobody except the committer can write them. (Imagine an explicit @docsguy role for documenting commits along with writing ticket-based documentation.) What if VCSs used a single file or a folder, like .gitcommits, where anyone could append any sort of info in the same commit, so it could be a part of it. Then, when you commit a feature, you add to this file(-s): @@ @@ +--- +added websocket support to the server + /ws - main socket + /ws-events - events socket And few commits later you decide to extend it, editing the same record: @@ @@ +--- +added json-rpc over websockets + /ws-json-rpc And VCS would then extract these records at `git log`: ... 4509812 added websocket support to the server 0732691 <no .gitcommits message> 8712389 added json-rpc over websockets Few commits later @docsguy expand on json-rpc: @@ @@ --- -added json-rpc over websockets +added lifetime-related json-rpc over websockets +task: ./tasks/1873.md +supports 'start' and 'stop' methods: ./doc/ws-lifetime.md /ws-json-rpc @@ @@ +--- +enhanced commit descriptions A tasks/1873.md A doc/ws-lifetime.md 4509812 added websocket support to the server 0732691 <no .gitcommits message> 8712389 added lifetime-related json-rpc over websockets 6034007 enhanced commit descriptions Full commit messages would then be just diffs. Also, one could write a commit message gradually, with the sources they are modifying. Or write two commit messages at once (because we all do commit two+ changes sometimes): @@ @@ +--- +refactored foo bar heavily, @docsguy please expand +--- +fixed a bug in baz, didn't care to backport ... 0923423 refactored foo bar heavily, @docsguy please expand fixed a bug in baz, didn't care to backport
    - nitrogen 5y ago
      I've never used git-notes, but it sounds like this is what you are describing: https://git-scm.com/docs/git-notes https://git-scm.com/docs/git-notes
      - wruza 5y ago
        While looking similar, they are something different, not versioned in the same way (alongside) as content, or editing a commit message.
- u801e 5y ago
  > What has gotten me the most value is having either the branch or the commit message tie back to a ticket somewhere. -That- has the original bug, the comment thread that led to the decision around why this particular fix, any additional comments around tradeoffs we were aware of, and what other options we dispensed with, etc. That works until the bug tracker goes down or the company decides to use a different bug tracker and the import doesn't preserve information, or the link in the commit message doesn't resolve to the corresponding ticket in the new bug tracker. This is far less likely to happen to the git history given that it's distributed. That being said, adding information to the merge commit message linking to the discussion or actually summarizing it in the commit message itself would definitely be an improvement. The merge commit has references to the commit the branch is based off of and the head commit of the branch, so you can limit git log output to just commits in the branch long after it has been merged.
- acchow 5y ago
  I believe commit messages should also summarize the context.
- randomswede 5y ago
  A well-written commit message should explain "why", this may partially consist of linking to external things (bug tickets, whatever). Although it is probably important to have enough of a "why" that the reviewer can make an informed decision if they need to go check the external reference or can continue with the review as-is. I ended up writing https://github.com/vatine/sressays/blob/main/change-requests.md https://github.com/vatine/sressays/blob/main/change-requests... to try to clarify to myself what I thought a good change request ("PR", "CL", "CR", whatever you want to call them) needs.
jay_kyburz 5y ago
Put the reason for the weird code in the comments explaining why it is. Don't make somebody run git blame.
bsder 5y ago
> If the commit subject rather, is "bugfix flaky builds", followed by a message that explains what the flakiness was, why you think the change will fix it, what other bugs or limitations you were working around, and what upstream changes you might be waiting on that prevented further work, you're in a much better position. Those are very different needs. "Why?" belongs in code as a comment. "How?" only sometimes belongs in a comment--generally if the code is "clever". "What?" generally belongs in the commit message as it can touch multiple files and subsystems. "Who?" and "When?" generally belong in your ticketing system.
sillysaurusx 5y ago
I fixed a bug the other day that I was so embarrassed about, I intentionally left the commit message cryptic. (It was a personal project.) Sometimes the best documentation is seared into your soul as a mark of shame. I think I’ll wake up a few times wincing about it.
- Red_Leaves_Flyy 5y ago
  Spare me your shame. Should someone inherit your project and end up fixing another bug in that part of the code they may be benefit from any information you share. Shame is temporary, public repos are not.
- dwaltrip 5y ago
  To err is human. Don’t feel bad about it. You fixed it :) (I say this as someone who has a track record of being too hard on myself!)
- JKCalhoun 5y ago
  A team I worked with had a fun little habit I have since borrowed: you add a "BOGUS" comment next to the offending line. Sort of like: // BOGUS: assuming 'x' will never be greater than 1024. Sort of tells future engineers, yeah, I know it's shit.
  - radlad 5y ago
    // I'm so sorry... A comment I left that I am sometimes reminded of by ex-coworkers still at that company.
mleonhard 5y ago
Code review discussions are precious context. Unfortunately, git does not keep them. This is a major shortcoming of git. We need a new source code management tool that stores code review comments. It can lower the cost of software maintenance.

by Yen 5y ago

lostcolony 5y ago

Eh, I'm not sure I agree. What has gotten me the most value is having either the branch or the commit message tie back to a ticket somewhere. -That- has the original bug, the comment thread that led to the decision around why this particular fix, any additional comments around tradeoffs we were aware of, and what other options we dispensed with, etc. A well written commit message might explain what the issue was, but it won't have anywhere near the context the ticket and resulting comment thread should have.

V-2 5y ago
These two aren't mutually exclusive. Tickets, however, have lower long-term survivability (in my experience). Outsourcing, migrations, there are many scenarios in which the original tickets become inaccessible over time - and some codebases do last for years and years. Meanwhile the repository content (and thus the complete version history) usually survives as-is.
- wruza 5y ago
  The commit message idea always felt a little strange/off to me. It's a string that you can't (generally) fix/extend later for those who may seek this information. Also nobody except the committer can write them. (Imagine an explicit @docsguy role for documenting commits along with writing ticket-based documentation.) What if VCSs used a single file or a folder, like .gitcommits, where anyone could append any sort of info in the same commit, so it could be a part of it. Then, when you commit a feature, you add to this file(-s): @@ @@ +--- +added websocket support to the server + /ws - main socket + /ws-events - events socket And few commits later you decide to extend it, editing the same record: @@ @@ +--- +added json-rpc over websockets + /ws-json-rpc And VCS would then extract these records at `git log`: ... 4509812 added websocket support to the server 0732691 <no .gitcommits message> 8712389 added json-rpc over websockets Few commits later @docsguy expand on json-rpc: @@ @@ --- -added json-rpc over websockets +added lifetime-related json-rpc over websockets +task: ./tasks/1873.md +supports 'start' and 'stop' methods: ./doc/ws-lifetime.md /ws-json-rpc @@ @@ +--- +enhanced commit descriptions A tasks/1873.md A doc/ws-lifetime.md 4509812 added websocket support to the server 0732691 <no .gitcommits message> 8712389 added lifetime-related json-rpc over websockets 6034007 enhanced commit descriptions Full commit messages would then be just diffs. Also, one could write a commit message gradually, with the sources they are modifying. Or write two commit messages at once (because we all do commit two+ changes sometimes): @@ @@ +--- +refactored foo bar heavily, @docsguy please expand +--- +fixed a bug in baz, didn't care to backport ... 0923423 refactored foo bar heavily, @docsguy please expand fixed a bug in baz, didn't care to backport
  - nitrogen 5y ago
    I've never used git-notes, but it sounds like this is what you are describing: https://git-scm.com/docs/git-notes https://git-scm.com/docs/git-notes
    - wruza 5y ago
      While looking similar, they are something different, not versioned in the same way (alongside) as content, or editing a commit message.
u801e 5y ago
> What has gotten me the most value is having either the branch or the commit message tie back to a ticket somewhere. -That- has the original bug, the comment thread that led to the decision around why this particular fix, any additional comments around tradeoffs we were aware of, and what other options we dispensed with, etc. That works until the bug tracker goes down or the company decides to use a different bug tracker and the import doesn't preserve information, or the link in the commit message doesn't resolve to the corresponding ticket in the new bug tracker. This is far less likely to happen to the git history given that it's distributed. That being said, adding information to the merge commit message linking to the discussion or actually summarizing it in the commit message itself would definitely be an improvement. The merge commit has references to the commit the branch is based off of and the head commit of the branch, so you can limit git log output to just commits in the branch long after it has been merged.
acchow 5y ago
I believe commit messages should also summarize the context.
randomswede 5y ago
A well-written commit message should explain "why", this may partially consist of linking to external things (bug tickets, whatever). Although it is probably important to have enough of a "why" that the reviewer can make an informed decision if they need to go check the external reference or can continue with the review as-is. I ended up writing https://github.com/vatine/sressays/blob/main/change-requests.md https://github.com/vatine/sressays/blob/main/change-requests... to try to clarify to myself what I thought a good change request ("PR", "CL", "CR", whatever you want to call them) needs.

jay_kyburz 5y ago

Put the reason for the weird code in the comments explaining why it is. Don't make somebody run git blame.

bsder 5y ago

> If the commit subject rather, is "bugfix flaky builds", followed by a message that explains what the flakiness was, why you think the change will fix it, what other bugs or limitations you were working around, and what upstream changes you might be waiting on that prevented further work, you're in a much better position. Those are very different needs. "Why?" belongs in code as a comment. "How?" only sometimes belongs in a comment--generally if the code is "clever". "What?" generally belongs in the commit message as it can touch multiple files and subsystems. "Who?" and "When?" generally belong in your ticketing system.

sillysaurusx 5y ago

I fixed a bug the other day that I was so embarrassed about, I intentionally left the commit message cryptic. (It was a personal project.) Sometimes the best documentation is seared into your soul as a mark of shame. I think I’ll wake up a few times wincing about it.

Red_Leaves_Flyy 5y ago
Spare me your shame. Should someone inherit your project and end up fixing another bug in that part of the code they may be benefit from any information you share. Shame is temporary, public repos are not.
dwaltrip 5y ago
To err is human. Don’t feel bad about it. You fixed it :) (I say this as someone who has a track record of being too hard on myself!)
JKCalhoun 5y ago
A team I worked with had a fun little habit I have since borrowed: you add a "BOGUS" comment next to the offending line. Sort of like: // BOGUS: assuming 'x' will never be greater than 1024. Sort of tells future engineers, yeah, I know it's shit.
- radlad 5y ago
  // I'm so sorry... A comment I left that I am sometimes reminded of by ex-coworkers still at that company.

mleonhard 5y ago

Code review discussions are precious context. Unfortunately, git does not keep them. This is a major shortcoming of git. We need a new source code management tool that stores code review comments. It can lower the cost of software maintenance.