4 ms·
> thoughts associated with code - "spoke with Titus and Jen about this, and the loop needs to be broken up because foobar...". most of the time if I embed comme
by calcifer 6y ago
> thoughts associated with code - "spoke with Titus and Jen about this, and the loop needs to be broken up because foobar...". most of the time if I embed comments like that, someone blocks a PR or just rips them out in the name of "cleanliness", then 3 years later people are wondering "why was this done this way?"
I really hate it when people do this. The commit message should be all about the why (the diff already tells me the what), getting rid of it means removing the only useful bit of info from the commit message.
- mgkimsal 6y agoThere's code comments and commit messages. I was referring to code comments, not messages. I am on some projects where others are really strict about "no superfluous comments". Yet... the thing that's helped most when looking at 5-10 year old code is someone's multi-line comment about what decision led to something (sometimes with decision maker names, dates, etc) and some reasoning. None of that is remotely discoverable in things like confluence (at least in any project I've worked on in the last 10 years or so).
- xmprt 6y agoIt's crazy that businesses that are built on top of code spend hours in meetings to come to a decision that isn't documented anywhere for people to see 2 years down the line. These are team leads who have worked for close to a decade. They must realize the value in documentation by this point.
- im3w1l 6y agogit blame can bring up relevant commits.