Re:git-appraise – Distributed Code Review for Git
by cdogl on Friday August 11, 2023 @07:22AM
(#37087409)
I prefer clean code that doesn’t have comments except as doc strings for various parsers on declarations and in areas that are particularly surprising.
If I want to know why something was done, I expect to be able to use git log or git blame on the file or line and get find a commit message, issue tracker link or pull request reference that I can pursue.
Re:git-appraise – Distributed Code Review for Git
by thfuran on Friday August 11, 2023 @07:55AM
(#37087651)
But then a single minor refactor means you have to dig through history after puzzling over something for long enough to decide that it's definitely no obvious instead of just seeing an inline explanation (or at least a link to one).
Re:git-appraise – Distributed Code Review for Git
by indymike on Friday August 11, 2023 @08:25AM
(#37087898)
Issue trackers, vcs and employees change. A meaningful comment stay as long as it is meaningful.
Re:git-appraise – Distributed Code Review for Git
by Corsome on Friday August 11, 2023 @09:34AM
(#37088527)
> A meaningful comment stay as long as it is meaningful.
Sometimes even longer :)
Re:git-appraise – Distributed Code Review for Git
by indymike on Saturday August 12, 2023 @12:38PM
(#37101901)
# TODO remove this
is my all time favorite.
Re:git-appraise – Distributed Code Review for Git
by avgcorrection on Friday August 11, 2023 @12:06PM
(#37090270)
A lot of commits in Linux contain links to where they were discussed (Kernel Lore archive or something).
Another thing that's easy, but often overlooked: putting relevant URLs in comments. The best comments explain why some approach was taken; linking to a discussion on JIRA, or the Stack Overflow answer we c̶o̶p̶y̶-̶p̶a̶s̶t̶e̶d̶ ̶f̶r̶o̶m̶ used as inspiration, is (a) quicker than writing a whole explanation, and (b) gives better evidence of what's going on (e.g. that the CTO explicitly asked for this-or-that; or that the SO question now has a better answer; etc.)