Re:Reducing technical debt by valuing comments as much as code
by layer8 on Tuesday January 31, 2023 @06:42PM
(#34604049)
What I would miss, in the above, is information about:
- where the page is being read from
- what page numbers the function accepts
- what happens if an invalid page number is specified (or if that’s deliberately undefined, stating that fact)
- other possible error conditions, if any
(I’ll assume that PageData already documents what “page” refers to in that context, because for me it’s not “self explanatory” just from the function signature you provided.)
I always assumed that behavior was dogmatic until, over many PRs, multiple members of the team commented that if I commented my code, it would be much easier to read. And comments of the above quality assuaged them.