Author Etiquette
The idea is to make a pull request easy on the reviewer. Another opportunity to reduce irrelevant cognitive load, and increase profit 💸.
This is done by providing as much context as possible.
- Link to ticket
- Link to designs
- A summary of the work done. this can be a few bullet points
- Explicitly point out areas you want the reviewer to pay close attention to
- Steps to reproduce (if it’s a bugfix)
- How to test - if you describe the happy path, the reviewer knows which areas to look out for error handling
Here’s a template you can refer to.
Michael Lynch has great articles about code review. He shares How to Make Your Code Reviewer Fall in Love with You
Naming Conventions
Branch Names
I’ve seen naming conventions exist at branch level, and commit messages.
When naming branches, usually the ticket number alone is enough. You can also prefix them to indicate the type of work being done
eg bug, hotfix, feat, chore etc.
Tyler mentioned:
personally I’m not a fan of the ticket number in the branch name because it adds noise. I’d rather have like
feat/submit-claim-logicor similar and on your PR you link the ticket there. If you’ve got the Jira/Github integration then it’s very useful because the branch will be populated in the ticket just by virtue of having the ticket number in the branch name so that’s pretty dope and useful depending on who’s looking at it
I agree, the real value in naming branches with ticket number is with the automation you can do with it.
The idea is to pick one approach as a team, and go with it.
Commit Messages
Commit messages accompanied with prefixes also provides rich context. Angular conventional commits is a good standard to start from. When done well, good commit messages are an area to provide rich context to your reviewer, it allows one to jump in and out of points of interest, and give more insight into how you came to your eventual solution.
Two articles on the topic:
Reviewer Etiquette
Michael Lynch has written very well detailed notes on doing code reviews well.