Hello Jr. Devs 👋,
Today, I’d like to clear up a bunch of misconceptions about what pull requests are & how to use them.
In this post we’ll cover:
- What a pull request really is (this is often confused)
- How to make great PR’s
- How to give/receive great code reviews
Let’s begin! 🌟
What is a Pull Request?
Technically — It’s a request to merge code from one git branch into another.
👆 this is the definition that most new developers start out with and I think it causes so many problems.
When it’s a “request” to be merged (aka, approved). It sounds like a binary pass/fail thing. Which it shouldn’t be.
What a pull request really is:
- A great tool to show/discuss/comment/get feedback on code changes
- A way to display in-progress or completed work
- Collaboration with your teammates/friends
- An evolving solution to a problem that you can change & add commits to over time
What a bad pull request looks like 👿
Notice the lack of details. From this, I have no idea what the pull request is about. You can do better.
What a good pull request looks like 😀
That’s a nice pull request!
The most important thing to remember when submitting a pull request. It’s not only about the code. The people reading these are your teammates/friends/humans.
- Make it human!
- Make it readable
- Include pictures/gifs & emoji
- Describe why you want to make the change that you are making
- If more changes are coming later in other PR’s — explain that
Take Advantage of the Files Changed Tab
Before sending your PR around for review. Go to the files changed tab and review your own code. Look at each file changed.
When you’re outside of your editor, the perspective is a bit different and you’ll notice mistakes you made that you didn’t notice before. Now’s your time to fix them before getting other eyes on your code.
Open Early and Often
Once you have a single commit, you can open a pull request. It does not need to be “done.” Throw a note or label on it that it’s not ready yet for review. I like to do this.
GitHub let’s you add todo lists to your PR’s. This is super useful. It communicates with the rest of your team what’s left. And I also find that it helps me clear up my thinking about what I want in this change & what I should work on next.
Then on the Pull Requests page, you’ll see your work in progress.
Having your code reviewed
When you first start as a Jr. Developer, getting feedback on your code can be an emotional experience. I promise you, this will go away and you’ll become very comfortable with the process soon enough.
1. This is your opportunity to learn
You have experienced developers telling you in a PR how to improve. THIS IS AMAZING. The best coding tips I’ve ever learned have come through code reviews. There is nothing better than a second set of eyes, especially those that have seen & written way more code than you, giving you specific/actionable feedback to accelerate your learning.
2. Don’t go on defense
Our natural response when anyone tells us we’re “wrong,” is to try to justify why we did it in the first place. You have to get past that natural instinct & open yourself up to feedback. Give it a few minutes, think about it & digest before reacting.
Remember, the reviewer is there to help you improve, not make you look stupid.
3. If someone says it’s hard to read, then it’s hard to read
When you’re writing code, you have the most context in your head & at that instant the solution is the most clear to you. Later, when others are reading it, they don’t have that context.
If they comment they are having trouble understanding/reading it: 9 times out of 10, it’s probably hard to read code. Try to refactor it to be more readable, ask them for help. You’ll thank yourself 6 months from now when you forget you ever wrote this code in the first place.
Being a good reviewer
Now that you’re a pro at receiving feedback. Let’s talk about giving it.
1. Give specific & actionable feedback!
🚫 bad feedback looks like this: “i don’t like how this is organized”
✅ specific and actionable feedback looks like this: “I think this would be better if the Foo class were namespaced under Widgets”
2. Be HUMAN
Receiving/giving feedback on your work can be hard/emotional. Emotion is hard to communicate through text. Liberal use of emoji 😀💯💜🌟 is encouraged.
3. Point out the positives
PR’s can turn into a list of things to improve. Don’t shy away from pointing out code that you like / things the person has done well. Your relationships with your teammates are more important than the code. Adding an occasional “nice! :smile:” goes a long way.
4. Keep it relevant to the PR
Often I’ll see reviewers writing their random thoughts about something else in a PR. “Hey Emily, we should build new feature xyz together next week”
Please don’t do this. It’s distracting & not helpful in the context of a PR.
Now, let’s review
- PR’s are a tool for reviewing code/ideas
- You can never open them too early
- Code reviews = huge opportunity to learn
- Give actionable/specific feedback
- Use emoji 😃🌟
That’s it for today Jr. Devs. Go forth and make killer Pull Requests! 💯