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