When I started my first job as a software developer, I felt like a fire hose of information was being sprayed at my brain. There was so much to learn, especially because I hadn’t ever worked with the main language (Ruby) that I would be coding in everyday outside of some V basic “hello, world”-type beginner projects. Most days in my new career felt overwhelming to say the least, but I wanted to do everything I could to succeed.

One way I had to orient myself in my new environment was pull requests (PRs). Documentation has always been my bag, so figuring out how to write useful PRs was less of my problem, although there was still a learning curve involved. For months, my biggest struggle with PRs as a newly minted developer was giving meaningful code reviews to colleagues and seniors. Half the time I felt my eyes glaze over trying to read through and understand code that was still quite literally a foreign language to me. Plenty of times I didn’t understand the syntax, what I was reading, what change was being implemented, or why it was important - sometimes I didn’t understand all three at once. I wanted to feel like I could actually contribute to conversations held and issues raised in PRs, but for a long time, felt like I didn’t have the knowledge base to do so.

Over time, I started to dial in how I, as a junior engineer, could meaningfully contribute to PRs. I asked senior engineers for feedback on how I could improve my PR processes, and what I could do to better understand and engage in technical conversations. I learned when I should ask questions about code or syntax I didn’t understand, and was reminded “oh yeah, (sometimes) documentation exists for something I don’t understand.” I learned that I don’t always have to have a fully working solution to be able to spin up a new PR. I learned how to use tools like automated tests, commit history, tailing logs in Heroku, etc. to get a more thorough understanding of what I was reading and to raise questions and concerns about how that code worked.

However, I was still getting frustrated that I couldn’t always remember what I could do to better review code written by other developers, or what I could do to more thoroughly check my own code for errors or refactoring opportunities that I could have caught in my own PRs to save my colleagues time in their reviews. Even just remembering what all I could try and do to push myself further into blockers I was having without senior support and implementing better debugging techniques during the review process was still a struggle.

This might seem unrelated, but stick with me here - I worked for many years in the service industry before going back to school at a coding boot camp. When I worked in bars and restaurants, there was always a laminated checklist somewhere behind the bar or in the server station waiting for someone to walk through all the opening duties, closing duties, and what’s called “side work” - things like polishing silverware, folding napkins and so forth that keep the restaurant prepared and staff busy in slow moments. Even if I had done the same opening or closing duties 100s of times, some days I still used those lists to guide me at the beginning and end of my shifts. I knew I could still forget something on the list, or my ADHD brain would not be a pal and squirrel away my focus elsewhere.

Harkening back to my years in the service industry and recognizing the limitations of my neurodiverse brain, I remembered that these workflow checklists were wildly valuable to me in my former career. Even if I had done a process a hundred times over, having a list in front of me to keep me on track and ensure I didn’t accidentally skip steps was incredibly beneficial for my brain to be more systematic. I realized I could apply this same principle to my new job. So, I started building a checklist to work with when both writing and providing code reviews.

Knowing other new and burgeoning developers like myself would likely benefit from the knowledge I have gained in my first few years of experience writing and reviewing PRs, I wanted to share what I’ve learned, so that others can contribute more in their own first developer roles and hopefully level up faster in their careers. I’ll share what I’ve found to be useful tools both for submitting my own code in PRs, as well as reviewing PRs.

Submitting Better PRs for your Code.

1. A good PR starts with a meaningful commit history that tells the story of what change you have made from beginning to end of your changes. a. Commit messages should be with a quick, concise synopsis of the change expressed because of the character limit that will be displayed in commit history. b. However, you can think of the character-limited commit as the “header”; you can also add additional “body” information inside a commit with more in-depth knowledge sharing about why you made that change, links to the resources used, the original task’s ID if you use a task management system, etc. Adding more body to a commit can provide valuable insights into a change when inspecting git history, and can be easier than trying to find an obscure, closed PR in the annals of your org’s repositories. If you use VS Code’s source control or a tool like Tower to make commits, their UI for adding body to your commits is really straightforward, but the Git CLI also allows you to do a simple carriage return to add this body in as well. (And pro tip, the git CLI recognizes Markdown syntax!) For example:

git commit -m "Add this specific feature ...

This specific feature used to do A, but now it does X, Y, Z after we realized A was limiting our <insert business or technical reasoning here>. This change in the feature now provides <insert value here>. You cannot make this feature do B like we originally set out to do in task [CU-#a3s3d4](www.your-task-link-here.com) since B is incompatible with the version of <insert tool here>. For further information on this incompatibility, please read [this piece of documentation](www.documentation.com)."

1. A good PR includes a clear written description. a. If writing a new feature, describe what this new feature does and why it was asked for - i.e explain the purpose of your change. b. If refactoring or adjusting an existing feature, describe why this change is necessary or useful. c. If you had to deviate from the original requirements of the task, explain your reasoning and describe how your solution to the problem is/could be preferable. d. If you started trying to solve a problem in one way but realized that solution wasn’t going to do what you needed it to or wasn’t a solution at all for the problem at hand, describe your process. e. If your org tests PRs in testing environments, i.e. in a review or test application that is a replica of a production environment but is used for internal testing purposes only, include links to the review app that demonstrate the changes you made. f. Include corresponding links to your production app for comparison to the new changes in your testing environment - before & after shots, if you will. g. Explain what people should look for and test in the live links. h. If the change is not a visual one, include some form of evidence if you can; e.g. include stats about a performance change, provide a CSV of a script of the results, etc. i. Include any questions, pain points, or blockers; PRs do not have to be perfect working examples. They can be a forum for requesting help and feedback on issues that have presented themselves during your development process. j. Learning some basic Markdown syntax can be really beneficial to include even things like headers, bullets, hyperlinks, checkboxes, tables, and so on in your PR description. k. Include before and after screenshots if the changes you’ve made are visual.
2. Do some science and test that the links you have included demonstrate your changes in the review apps yourself before asking for reviewers. Sometimes, a change will work in your local environment, but things go haywire in a testing environment, or you may have just simply missed a detail or two.
3. Before adding reviewers, take the opportunity to read through your own code in PR format to see if there are any missing details or refactor opportunities. Reviewing your own code in a different environment outside of your code editor can be incredibly beneficial to help you see things you weren’t seeing before. Viewing code in a PR format cuts out all the extra noise from other files you’re not working with to give a condensed snapshot of the change you’re working on, too.
4. Similarly, before you add reviewers, you should also consider if there is anything you can refactor, DRY up, clean up, make more readable, name more clearly, etc.

Providing Better PRs for Others

Some of the same rules apply across the board, whether you are asking for reviews or providing one for someone else.

1. Test the feature change if there is something that can be tested in a review app (e.g. submit a new form, compare visual changes between prod & review, etc.). When you’re looking at visual changes, does anything seem off? Remember that you can inspect a page through your preferred browser’s dev tools, and see if something funky happening in the markup or CSS is an attributing cause.
2. Go through all steps of testing that a change works. So you see that the new form doesn’t throw errors in the browser and exists as expected? Cool. Can you interact with everything in that form in the manner that you would expect? What happens on submission of the form? What happens if you re-submit or edit something in the form? What happens when you delete a new entry entirely? Put your Quality Assurance hat on for a bit and see what you can break. Look for tiny details like incorrect punctuation and big details like an entirely new page working.
3. Do some science to confirm with evidence that what you’re seeing works as it looks like it will work at face value. a. If the change is architectural in nature, e.g. updating a gem or Docker file or updating the version of your operating language, pull that branch into your local environment and play around with how this change works in your environment. Can you still build your Docker container? Can you still access the main landing pages of your application? Can you still run tests successfully? b. If a PR description doesn’t explicitly say, and you don’t exactly know what you could be looking for or testing out in an architectural change, ask. Understanding and anticipating the ins and outs of software architecture should not be an expectation of understanding in your junior role. c. If the PR is for a new script (e.g. a rake task if you’re a Ruby/Rails person like me), run the script line by line through your local environment’s console to confirm that the results are what you expect. *Bonus - if you don’t yet understand what a script is doing, this is a great way to get hands on and walk through the code line by line until you do better understand. Learning opportunities!
4. Ensure code abides by established conventions. a. Does your company have styleguides for HTML + CSS/Sass? Compare existing styleguides to the markup in a new feature to ensure consistency. b. Are accessibility and security best practices like OWASP’s Top 10 set out by your company or general industry standards being followed? c. Does your company have specific code language styleguides or best practices? For example, do they want to avoid hard-coded text in favor of translatable I18n dictionary entries? Are there internal methods (or even in-built methods to your language/framework) that you could be using instead of doing something from scratch? Look for small details like this to ensure code is meeting company quality standards. d. Does the code meet the language’s best practice standards? E.g. if you’re working in Ruby, are you using single quotes consistently unless there is a string that needs interpolating? Is indentation correct?
5. Ask questions. If you don’t understand something, don’t be afraid to raise a hand for help. Challenge yourself to find and learn the answer yourself first, but know that it is expected that everyone will have questions and need help sometimes, especially when first starting out.

Learning how to write cleaner, more thorough PRs takes time, and so does being able to give meaningful code reviews for your teammates. Working more procedurally with a checklist of deliverables and items to review every time you submit or review a PR can be significantly less stressful and more effective. Doing so can reduce back and forth reviewing with teammates, help you level up your technical skills, and get you contributing a higher level of code and feedback for peers. I hope you’ll find some of these tips helpful and can use them to level you up in your technical career faster.