💾 Archived View for bbs.geminispace.org › s › programming › 4473 captured on 2023-09-08 at 17:09:41. Gemini links have been rewritten to link to archived content
-=-=-=-=-=-=-
I like the recommendation in this article to 'label' your comments and may try to bring that to work. What other practices to people use when doing code reviews?
gemi.dev/cgi-bin/waffle.cgi/article?https%3A%2F%2Fwww.m31coding.com%2Fblog%2Fsemantic-reviews.html
2023-08-18 · 3 weeks ago
Yes, it helps a lot to set the tone. "Optional:", "If you like:" and "Nitpick:" are good. The last ackowledges that it's an annoying fix to apply, which goes some way to making it less painful to do so :)
Tip 1) Don't use "you" within code-review comments. It can come off as accusatory, and moreover it's not even really accurate since the code is also the reviewer's responsibility. So instead of:
"You bungled the thing here"
I would just do:
"This thing is bungled in this way"
"We" statements also go a long way. Rather than:
"You should format your comment in this other way"
do:
"We usually format our comments in this other way"
Tip 2) There are two kinds of changes: changes which will be easy to make later, and changes which are hard to make later.
Changes which are easy to make later are stuff like renaming a variable within some small scope, or the organization of some logical thread into various functions.
Changes that are hard are stuff like database schemas, public APIs, and shared package functionality. Basically stuff which will be depended on from multiple spots.
I tend to not leave comments about the former. If the code works, even if I don't like it, it can be changed later if it turns out to matter. The latter are the more important ones. The more a thing is dependended on, the more important that it's correct the first time.