Comments can go rapidly out of date and rarely get updated properly to reflect new changes in code.
As a result, comments lie and can’t be trusted, and the only source of truth is actual code.
Re:Syntax Highlighting Is Backwards (2018)
by nikisweeting on Friday November 29, 2019 @02:56PM
(#21666459)
I've people on previous teams that thought this, and their comments were consistently the ones that were the most out-of-date because they never valued fixing them. If you value comment accuracy during PR reviews then you're less likely to end up in that situation in the first place.
Re:Syntax Highlighting Is Backwards (2018)
by throwaway40324 on Friday November 29, 2019 @05:19PM
(#21667159)
This. I totally agree.
One fallacy I've seen is a reviewer only looking at the diff on Github, where a minor change in the middle of a function is made, and they don't expand the diff to notice that the new change completely invalidates a comment, params, call signature, return value..etc.
WHY not WHAT really helped me out. WHY is this thing here instead of WHAT it is can give a line like i++; a vastly different comment and implication for the reader.