Re:Writing Well-Documented Code – Learn from Examples
by oxfeed65261 on Saturday September 04, 2021 @05:39PM
(#28419529)
…and on the reviewer(s) who accepted the code change even though the comments no longer match the code.
[ Parent
| on HN ]
Re:Writing Well-Documented Code – Learn from Examples
by Gh0stRAT on Saturday September 04, 2021 @07:52PM
(#28420499)
I agree, but git and most code reviewing tools I've used only show a few lines of surrounding context so the reviewers might not even realize there's a comment further up that needs updating.
Re:Writing Well-Documented Code – Learn from Examples
by msbarnett on Sunday September 05, 2021 @03:20PM
(#28426951)
Generally speaking, for all but the smallest of changes you should never only review the diff, but pop open the actual file on that branch (GitHub makes this fairly easy, I can't speak to other tooling) and consider the change in the context of the surrounding code. Does it contradict comments? Needlessly duplicate code from elsewhere in the file instead of creating a single function to be used in both places? Shadow variables confusingly? Add yet another 5 lines to a 100 line function instead of leaving the code better than it found it?
You can't really judge any of this if you're just eyeballing a diff. Diffs are just the starting point for a review, and while tooling could make this easier, the full file is always just a git checkout away.