On a previous engineering team, I once proposed a comment tagging convention that evolved over time to a stable place and ended up being quite useful for us. Unlike Conventional Comments, though, our main motivation was to communicate _expectations_ clearly, so the person receiving the review has enough information to decide what _action_ to take.

The Conventional Comments labels help a little, but requests for action are lumped under "suggestion" and "nitpick" and "chore", which I don't find to be useful distinctions. "Suggestion" doesn't tell me whether the reviewer is just offering an idea for improvement or pointing out something that must be addressed, and doesn't tell me whether I need to check back with the reviewer before merging my change. If I get a "question", then after I answer the question, is it okay to merge or not? "Issue" doesn't tell me if the issue is big enough to block the PR.

——

Here's our system:

• [help] means "I need help understanding this PR". I can't do a useful review of this PR without a better understanding. Please talk to me before proceeding.

• [fix] means "fix now". I've identified a problem; please fix it before merging. If you don't agree that this needs to be fixed, or you think we should do something different from my proposed action, please discuss it with me before merging -- we probably have a significant difference in understanding that is important to sort out.

• [fix?] means "fix now if bug". This looks like it might be a bug, but I'm not sure; please evaluate it, and if it's indeed a bug, treat it as a [fix].

• [minifix] means "fix now if small". I'm asking for this to be fixed before merging because I think it will take <30 seconds. If it takes longer, forget it.

• [postfix] means "postponable fix". This is important enough that it must be fixed, but it doesn't need to delay urgent work. You can decide if you want to do it before or after merging this PR.

• [cbb] means "optional, objective" ("could be better"). This could be better in the way I'm suggesting, but it's not so important that it must be fixed before merging. I'm making a recommendation as a good practice for next time.

• [taste] means "optional, subjective". I'm suggesting an improvement, and I'm acknowledging that it's a personal preference. I am not demanding that you change your preferences long-term, but I'm offering it because I find this practice useful and think you might find it useful too. If you like it, use it.

• [fyi] means "for your information". No action needed. This might be mentoring advice, or a reference to something else that's relevant, or a thing to note for the future, etc.

——

I like this system because each tag makes it very clear exactly what action is required before merging and under what conditions there needs to be further discussion with the reviewer.

[help], [fix], and [fix?] are blocking: the PR cannot be merged as-is without discussion. For [fix] the communication loop must be closed with the reviewer; for [fix?] the communication loop can be open.

[minifix], [postfix], [cbb], and [taste] are non-blocking: each one identifies _why_ the suggestion was made so the receiver can decide whether or not to take action. In practice, we found that these 4 categories did pretty well at covering the most common reasons behind suggested actions.

Notice: [fix] and [minifix] aren't about whether the change is big or small. A [fix] could be big or small; the important information is that it's mandatory. The smallness indicated by [minifix] is relevant only because the smallness is the _reason_ for the suggestion.

Notice: There's no [chore] or [style] or [nitpick] category. [style] doesn't help, because we still don't know whether the style change is mandatory or merely recommended. It doesn't matter what kind of thing we're asking for; what matters is what needs to be done about it.