Document your code just by hitting “record”

Re:Document your code just by hitting “record” by calcifer on Tuesday November 03, 2020 @06:41PM (#24985285)

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

[ Parent | on HN ]

Re:Document your code just by hitting “record” by mgkimsal on Tuesday November 03, 2020 @07:06PM (#24985460)

There'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).

[ Parent | on HN ]

Re:Document your code just by hitting “record” by xmprt on Tuesday November 03, 2020 @07:10PM (#24985484)

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

[ Parent | on HN ]

Re:Document your code just by hitting “record” by im3w1l on Tuesday November 03, 2020 @07:41PM (#24985666)

git blame can bring up relevant commits.

[ Parent | on HN ]