One of the most frustrating things you can experience as a developer is writing a bunch of code, spending a bunch of time working on features, and then waiting around for a PR review. In today's episode, we're going to talk about ways that you can make your PRs a little bit better. These are poll requests. We talked about poll requests in the last episode of Developer Teafrom the opposite side. How can you be a better reviewer? But now we're going to talk about it from the submitting side. My name is Jonathan Cutrell and you're listening to Developer Tea and my goal on this show is to driven developers like you, find clarity, perspective, and purpose in their careers. The first point I'd like to make about having good PRs and hoping that other people will review them, which is kind of the goal. The goal of having a good PR, a good poll request, is that other people will have all the information that they need to be able to review that poll request with the least possible friction. Ideally, what this means is that the review, the responses that you receive, the comments on your code that change requests that are provided on your code, that they're all productive, that you're not having to explain yourself multiple times or try to make something that is really confusing in your code or in your PR, try to distill it down in comments. Instead, what we want to see as engineers is poll requests that are very clear, they're concise, they make sense to the problem, they're scaled to the problem. There is enough information and data provided for decisions that were made when it's necessary and it doesn't go overboard on optimization, there's not a lot of clever code. Really what we're looking for in a poll request is something that allows me as the reviewer to clearly know what's going on and approve that change. I'm going to give you some specific things to pay attention to in your poll request. This is a skill set, creating poll requests that are narrow and specific enough and clear enough. And this is a skill set because this requires that as you are writing your code, as you are working on a given feature that you're considering what does this poll request ultimately look like to the reviewer. You have to put yourself in the reviewers' shoes. And in fact, that is my first recommendation. If you want to have a good poll request, review your own code first. Review your own code first. What does this mean? Well, the evidence of you reviewing your own code might be comments on lines of code and it doesn't even necessarily have to be comments in the code itself. You can review your own poll request almost like someone else might review it. You know, most platforms like GitHub, you can't be officially a reviewer. You can't approve your own poll request, but you can go through and provide points of clarification and put on your reviewer hat. Now this is really important to understand here. This isn't just a formality. When you put on the reviewer hat, you are likely to see your code differently than when you are writing it. This is a very functional move that you make by reviewing your own code because this changes the perspective or the seat that you are sitting in. You are exchanging one hat for another. For the submission hat, your goal is to hopefully get the code approved so you can get it moved along so you can ship code ultimately provide value to the business, et cetera. From the reviewing perspective, as we mentioned on the last episode, the goal is to come to a resolution on the PR. But here's the critical factor. When you put on the reviewing hat, you see your code through fresh eyes of specifically criticism. You want to adopt the critical point of view and this operates on two dimensions. The first dimension is if you adopt the critical point of view for your own code, you might catch something before another reviewer catches it. This will lower the number of iterations necessary per pull request. Guarantee this is true. If you start implementing this on your teams, if you require yourself or require their author to go through and review as if they were a reviewer on their own pull request, you're likely to see many small things, very simple errors, that otherwise would take a cycle. Somebody coming in, reviewing, asking for a change request and then the original author of that code, having to go back and submit that change and then re-request the review. If the author, self-reviews, a lot of those things tend to be caught when they explicitly put on that reviewer hat. So there's that one piece of that kind of practical putting on the reviewer hat changes your perspective. But the second thing that it does is it gets you on the same side as the reviewer. In some ways, pull request can feel adversarial. The person who is submitting the code is somewhat of an adversary to the person who is reviewing it. And this is not very good necessarily because you both want to have a shared common goal. So if you can get into the critical mindset of your own code, it's possible that you'll be more likely to detach your ego from that code because now the goal is to make it better. That's my first recommendation in today's episode, my first recommendation for being a better pull request author. We're going to take a quick sponsor break and then we're going to come back and talk about two more pieces of advice that I have for you to be a better pull request author. Today's episode is sponsored by Zbrand. Zbrand helps you launch a product with minimal visual brand design resources without internal designers, costly agencies or questionable freelancers. This is an excellent product for engineers who are building out their side hustle and you realize the importance of branding. Because Zbrand you can launch your product without investing too much time and money on branding, which means your team can give 100% focus to product development by asking some simple questions about your product. Zebrand's AI based algorithm creates a uniquely tailored brand toolkit full of branding and marketing essentials, including fonts, color palettes, pitch deck, templates and much more. And here's the critical point. Zbranding is offering these marketing assets for 60% off for this week only, that's 60% off for this week only, head over to zebranding.com. That's zebranding.com to get started today. Thanks again to Zebranding for sponsoring today's episode of Developer Tea. The next piece of advice that I have for you as an author of pull requests is to be detailed. Be detailed. Now what does this mean? This is actually a bunch of quick hit. You can even probably create a checklist out of this list I'm getting ready to give you. These are a bunch of quick, simple things that will make your pull requests much easier to review. Okay, so let's get started here. The first thing is to make sure that you have a good descriptive title. This is very simple, but your title should explain what your code is doing that is different from what the code previously did. It's possible that your title is fixes bug with drop down. This is something very simple, or it may be a little bit bigger of a title that's more descriptive or even more specific to your application. But the most critical thing here is that when I read the title, I should know essentially what's going on in this pull request. That brings me to my second point, no extraneous code. Don't accidentally include or try to sneak in extra pieces, extra details, extra features, little fixes, typos, etc. These are the kinds of things that should be in their own pull requests. So if you have them in this pull request, it only serves to be confusing for the reviewer. It's not a lot of extra work. There's sometimes when we accidentally commit these things into our repo. It really isn't a lot of extra work. You can check that file out. Of course, we're not going to get into the technical details here. But the point of this is to focus your pull requests. Ensure that the changes that are in your pull requests are only for the items that you are addressing. Here's another very important one. Make sure your description is clear. Leave your description blank, certainly. When you do provide a description, make sure the description is clear. An easy format for this is explaining what was the case before you wrote your code. Another way to think about this is what is the motivation or the reason this PR exists and then describe what the PR does in very simple terms. If there's a lot of visual work that goes on really good, a kind of addition that you can add to this description is an animated GIF. You can take these on Mac. There's a program called LiceCap. You can probably find a similar program for Windows to create a little animated GIF out of whatever you changed visually and drop that into the pull request. If you have some kind of ticketing system or a management system for user stories, the description is a good place to link to those user stories. This is as much detail as you can explain, what is the context for this code? Why was it written and how does it accomplish what we're trying to accomplish? Everything that you can do to describe what you've done and why you've done it, that helps the reviewer get a summary before they dive into the code changes themselves. And the final thing you might find in descriptions is some kind of data driven proof for why you've chosen to do what you've done. Whether that's an AB test to show performance before and after or maybe it's a survey results that are explaining the justification for this particular decision. If some of this, it depends on your team and whether the product department in your company, for example, they might be handling some of those things, but as much detail as you can provide in the description, the better. Now there is a caveat here. Of course, don't provide details in your description that are significantly longer than what the PR deserves. And you have to decide what the PR deserves yourself. For example, if it's a one line change, you probably don't need 10 lines of description, but it's possible that that one line is really critical. And you do need that 10 lines of description. The point here is definitely don't go underboard. In other words, don't leave the description blank, but also don't go overboard. Reading the description should help not hinder the review process. So all of those is kind of small points where the larger point of being very detailed in your pull request. The final recommendation that I have for you to be a better pull request author is a very simple one. Keep in mind that pull request reviews are a benefit to you as an engineer. Pull request reviews are a benefit to you. They're not an impediment to your progress. They're not just an annoying formality. These moments of getting critical feedback, explicit feedback on your code that you've written, these are opportunities, opportunities to grow, but they're also moments where other engineers are setting aside the work that they are responsible for to come and help you finish your work. Most organizations do not provide strong incentive for reviewing other people's code. And so it's important to remember that other people reviewing your code, they probably have something that they would rather be doing or that they're more incentivized to do at the very least. And so if other people are providing you reviews on your code, then it's reasonable that you should reciprocate and provide reviews on their code. Having a good pull request author actually is very similar to being a good pull request reviewer. It's all about helping other engineers with the understanding that this is how teams function. Being willing to help each other out is critical to your collective success. If no one reviews your pull request, then your pull request is probably going to sit and never get merged. And the same is true for theirs. And so we must learn to collaborate and cooperate around each other's code better. Thanks so much for listening to today's episode of Developer Tea. Thank you again to Zebra and for sponsoring today's episode. Remember you can get 60% off marketing essentials. Head over to zebraand.com to get started today. Today's episode and every other episode of Developer Tea is available on spec.fm. This is only one of the many great podcasts that are on spec. Head over to spec.fm to find other wonderful shows that will help you grow as an engineer throughout your career. Developer Tea is created for developers who are growing in their careers and they care about other engineers who are growing in their careers as well. And so for that reason, I have a very simple request. If you can take a moment and share this episode or share another episode of the show or just the show in general with other developers in your communities, whether that community is digital, maybe on Twitter or in a Slack community, wherever your community of engineers that you collaborate with, maybe you work with them directly, whoever those engineers are, masking that if you really enjoy the show and you think other people can benefit from it, they share this show in those communities. Thank you so much for listening to today's episode. Today's episode was produced by Sarah Jackson. My name is Jonathan Cutrell and until next time, enjoy your tea.