In our Slack organization and Github pull request review, I have noticed a small pattern of using parentheses to soften or clarify the statements that we make. Sometimes it used by someone in a position of authority to emphasize that a comment is an idea, not a directive. Other times, it represents that things are not critical to address, but might be something that we want to look into.

I originally wanted to call this post “The Shipley Parenthetical” since Kyle uses it all of the time. Didn’t know if he thought of it this way / approves though. :)

In this post I’ll give a few examples of how this works and some thoughts on it.

Example 1

Just capturing a thought that would be helpful or is on the commenter’s mind, but wanting to be clear that there is no specific action item around this.

Will avoid further churn, IMO. (Down the road, we may even want a copywriter with clinical knowledge on or near the product team.)

Example 2

Hedging a comment about what might be the best with a bit of YAGNI:

That is probably my preferred order overall, with my additional comment that making it data instead of code might sidestep the matching problem entirely if it is worth it. (Not sure if it is yet.)

I think this is a good way of resolving the need to point out something that could be better while not committing us to doing it.

Example 3

Comment by author of pull request after a comment by reviewer to remove some code:

This interactor is actually part of the original code. Are we ready to start removing it?

(Not planning to restore here for that reason unless there are objections.)

I like this because it specifies a reason for not removing the code and states what the default behavior will be if an argument against it is not raised. It might be even better if the timeline for when the option to respond expires.

Example 4

In a review, after commenting on a specific issue, the next comment the reviewer makes is on the same issue in a different place. They said:

(Same thing here, sorry.)

I like this as a way of indicating that the reviewer is being empathetic while still showing that there are a few places where the same problem exists. This approach is better than “WRONG AGAIN” or equivalent statements.

Example 5

Interjecting into a pull request conversation to potentially clarify reviewer’s comment while still admitting imperfect knowledge:

I think @shipstar was saying for the right hand side of the expression, is there a foo field on baz? Or should it be bar? (At least that is how I read his comment.)

Example 6

Indicating that a comment is non-blocking, but that would be nice to have:

(Could also use .reject instead of .select if the intentional is filtering. Seems infinitesimally more semantic.)

Any thoughts?

This is kind of a new format of a post for me. Basically I’m harvesting artifacts for free blog posts from Slack and Github. Not sure that I would try it again, but it might be helpful / interesting to someone. (What did you think?)