21–30 of 49 posts
I've been a big fan of this approach for years (introduced to me by Conventional Comments [1]) - even though it may not always be necessary, it's a low-effort way to make sure you're not misunderstood. [1] https://conventionalcomments.org/
I've been a big fan of this approach for years (introduced to me by Conventional Comments [1]) - even though it may not always be necessary, it's a low-effort way to make sure you're not misunderstood. [1] https://conventionalcomments.org/
I'd previously tried Conventional Commits but I found the number of labels they suggest too many to keep in my head. The labels in post map well to how I think about comments.
So for example something that has 10 nitpicks I will let it pass because all it tells me is i'm a dick :)
Or just criticize and take criticism like its part of the job. Being perfect in it has huge costs.
All too often, eager young developers are told to, "do code reviews," without being given any instruction on how.
This can lead to all kinds of unproductive misunderstandings, such as:
- Interrogating the author's competence, Why did you add the fields to this struct instead of...
- Shaming people, You should know... or How could you miss something so obvious? etc
- Bikeshedding, this one is subtle and a huge source of wasted effort and a huge nuisance. When discussing the construction of a nuclear power plant the most well attended and heated discussion was what color to paint the bike shed. Consider if your comment would really change anything for the better or is it just creating busy work? Remember: personal preferences aren't important, and neither are superficial ones.
Simple things you can do to avoid these kinds of comments, sound more constructive and assertive: refrain from the use of the words "I," or "you." Use the non-personal pronouns, "this," "they," to talk about the code. Stick to facts and avoid personal preference: you might have written it differently but if the tests pass, the style fits the rest of the module, there are no lint warnings, etc; people shouldn't have to come to you to ask how you would have written it. And use labels as the article suggests: if you feel compelled to leave some helpful advice for a junior colleague that isn't necessary to get the code merged, leave a label to indicate your intention.
In a similar fashion, authors: make sure you're comfortable rejecting poorly written review comments, ignore unhelpful nit-picking, etc. Practice rejecting a few nitpicks once in a while. After all, you took the time to understand the problem and write the code in the first place. Some times reviewers dropping by at the last minute haven't taken the time to fully understand and appreciate the problem. If their suggestion would have you re-write half of the work you did and not materially change outcomes it's a sign they have no idea what they're talking about.
Or just criticize and take criticism like its part of the job. Being perfect in it has huge costs.
Taking unprofessional or deconstructive criticism is not part of the job.
Suggestion: read the article
> a lot of time and energy are spent coping with the general disadvantages of written communication, such as the lack of tone and body language
If you encounter criticism that could be improved, help improve it: https://chromium.googlesource.com/chromium/src/+/master/docs...
For the rest, isn't it obvious when an question is a question or a hint is hint? If you understand English then the meaning of each comment should be clear.
The only one that makes sense to me is the "suggestion", to clearly indicate that it is OK if the code is not changed or that the change is not that important. For the rest, isn't it obvious when an question is a question or a hint is hint? If you understand English then the meaning of each comment should be clear.
I've been a big fan of this approach for years (introduced to me by Conventional Comments [1]) - even though it may not always be necessary, it's a low-effort way to make sure you're not misunderstood. [1] https://conventionalcomments.org/
The only one that makes sense to me is the "suggestion", to clearly indicate that it is OK if the code is not changed or that the change is not that important. For the rest, isn't it obvious when an question is a question or a hint is hint? If you understand English then the meaning of each comment should be clear.
Nice post. However, imho with a good enough writing style it should be possible to convey the purpose of the text without an explicit label.
This "good enough writing style" must also be able to cross cultural borders - I dare to say even journalists don't get it right most of the time: * I've heard Kiwis say "F*ck you?" in lieu of "Seriously?" * A Brit who says "That is an interesting solution!" usually does not feel intellectually stimulated by the solution but is conveying that it is utter garbage. Thus, I very much like the proposed idea of well-defin…
I can be sarcastic but I have never directed sarcasm towards someone who I am reviewing. (Sarcasm towards third-party code is okay for me.)
I don't know if people who are using sarcasm would want to start labeling things like that as such, since it tends to detract from the intended effect.
Disclaimer: not a Brit.
The question label is interesting, since I often ask questions in code review. However, the answer is only sometimes relevant in terms of just learning something. Someone else reading the code having a question is a signal that the code may not be as obvious as it should be and therefore should be changed (if only by replying to the question in the form of an added comment). Of course sometimes the reviewer is just d…