News for hackers. Stuff that matters.
Re:Reducing technical debt by valuing comments as much as code by lumb63 on Tuesday January 31, 2023 @05:36PM (#34603355)
In my experience, one man’s “waste of time” is another man’s castle-in-the-head-building-time-saver. At my current company, if I have reasonable, self explanatory code, such as a function with the signature “read_page(page_num: u32) -> PageData”, they’ll gather it reads a page with the given page number and extracts the data. At my last company, if I wrote the same code, I’d receive a comment on my PR complaining I did not document it will enough. I would then add a comment that somehow only I was able to detect was snarkily written, something like “// reads the given page number and returns its data” and they would be happy as clams.

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.

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