Whenever pointing out a specific thing, describe the generic underlying idea as well. By adding context, the author doesn't feel scolded, rather understands the intent towards a broader rationale. (And might dispute the rationale, not the specific comment).
For example, "Make this method final." can be extended with "Generally, prefer making methods in this class final, as we want to avoid accidental overriding. We had bad bugs about that in the past.".
Single comment per category
Add only a single comment about a single category of issue, and have an agreement that authors should fix all relevant issues without asking.
For example, don't write "Remove trailing whitespace here" on 20 lines. Add only on one line, maybe saying "Remove trailing whitespace - other lines too" initially.
Style guide
Have a public style guide, so authors diverge less. Keep it updated with common mistakes.
Ask for correction first
If a piece of code looks quirky or impenetrable, don't tear it to pieces. Rather start by commenting "I'm confused by the control flow here. Could you make it cleaner or comment?" or "This looks complex, please simplify or add more tests.". Often the author knows a piece of code is quirky, and a small trigger nudges them to fix it up.
If the code still comes back complicated, then make specific improvement comments.
If you like these and want more, subscribe to (or better, prepurchase) my book!
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
My book Programming Without Anxiety will address code review. Some important bits here:
Explain the generic idea as well
Whenever pointing out a specific thing, describe the generic underlying idea as well. By adding context, the author doesn't feel scolded, rather understands the intent towards a broader rationale. (And might dispute the rationale, not the specific comment).
For example, "Make this method final." can be extended with "Generally, prefer making methods in this class final, as we want to avoid accidental overriding. We had bad bugs about that in the past.".
Single comment per category
Add only a single comment about a single category of issue, and have an agreement that authors should fix all relevant issues without asking.
For example, don't write "Remove trailing whitespace here" on 20 lines. Add only on one line, maybe saying "Remove trailing whitespace - other lines too" initially.
Style guide
Have a public style guide, so authors diverge less. Keep it updated with common mistakes.
Ask for correction first
If a piece of code looks quirky or impenetrable, don't tear it to pieces. Rather start by commenting "I'm confused by the control flow here. Could you make it cleaner or comment?" or "This looks complex, please simplify or add more tests.". Often the author knows a piece of code is quirky, and a small trigger nudges them to fix it up.
If the code still comes back complicated, then make specific improvement comments.
If you like these and want more, subscribe to (or better, prepurchase) my book!