[Yen]

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]

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.

[u801e]

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

[V-2]

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.

[randomswede]

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... to try to clarify to myself what I thought a good change request ("PR", "CL", "CR", whatever you want to call them) needs.

[acchow]

I believe commit messages should also summarize the context.

[sillysaurusx]

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]

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]

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]

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.

[jay_kyburz]

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

[mleonhard]

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.

[bsder]

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