In software development, Version Control Systems (VCS) are a way for developers to share their work with their team and other collaborators and also control versions of built software. Pull requests (PRs) are a key ingredients in VCS that allow developers to suggest changes, work together on solutions, and maintain a high standard of the code quality. However, PRs are not just the tool to merge code; they are one of the ways teams can communicate, collaborate and work better together.

You'll agree with me that how useful a PR is, heavily depends on how it is written. If the codes are well-structured and clean, a clear and simple PR would make the review process faster, reducing confusion, and effectively save time. Also it helps reviewers themselves write better feedback and creates a smoother working environment and/or relationship. On the other hand, if poorly written combined with messy project structure, it will take lots of time and also frustrate the reviewing team causing numerous errors and bugs which slows down the reviewing process.

However, seeing this issue occurring with some project startups is the reason why this article was written to let you know into some simple guidelines for writing better PRs. As the saying goes, Rome wasn't built in a day, and as such I do believe that if you are to take what you are about to read and apply it, you will be able to write better pull requests and thereby make code reviews less of a chore. As the saying goes, Rome wasn’t built in a day, and as such Thus, no matter you are fixing a bug or implementing a new feature, these tips I am going to share with you will be useful to write pull requests your team will love.

You'll thank me later. 🙂 But for now, let's dive in:

TL:DR

Are you wondering why your code reviews are always rejected, left untouched? Its simply because your pull requests are too big, too messy, and that's why everyone hates reviewing them. How do you fix this? By adhering to the instructions in this article.

9 Common Mistakes You Shouldn't Be Making In Your Pull Requests

This is so common among developers, especially for those just starting; they invested their time pouring out their energy and creativity in coding a cool project only to be rejected through a pull request. It is quite frustrating to invest so much time, effort, and resources into building a project, and in the end, it was rejected because of one little mistake. After all the hard work and dedication put into it, this is a really hard pill to swallow.

Newsflash! I've been there more times than I lost count already. Like in any project, I wanted to work on something awesome only to be let down; my efforts fell short of expectations as my reviewer's team rejected my work. It always left me questioning: What went wrong? What did I not do well? What was not in order? However, with time and experience, I’ve come to realize that many of these rejections boiled down to avoidable mistakes, especially the ones new devs are inevitable to make. If you’ve ever found yourself in this situation, take a moment to go through the following list of common mistakes made by developers. You might finally discover the reason as to why your pull requests are being turned down.

#1. Incorrect or Inconsistent formatting

Failure to correctly and consistently format your code before requesting a PR can create a chaotic feedback by your reviewer's team and that is a major problem. I cannot state enough here on how significant this issue is. I do understand that writing clean and clear codes might look like an insignificant aspect especially when you're so focused on trying to meet a deadline but clean code tells a lot about you and how attentive you are to details.

Inconsistent formatting leads to messy code and that is a big no-no in this industry. In my experience, not upholding to the formatting standards can make your work stand out for the wrong reasons. When I first started, I didn't give much thought to this. When I started my job, I’d format code in whatever way I thought was good, not realizing that I needed to stay consistent with the formatting standards put in place by the company I was working for (was a newbie then😁) It wasn’t until I had a pull request rejected for this very reason that I truly understood its importance.

But now, I make it a point to align with the existing formatting standards in the codebase, whether it’s the indentation style, spacing, or naming conventions. Its important to know that every company and repo has its own rules, and sticking to them shows respect for the team and makes your code easier for others to read and review.

Examples of poorly formatted codes on javascript and python

javascript

// Inconsistent brace placement
function method1() {
    return true;
}

function method2()
{
    return false;
}

python

# Inconsistent (mixing tabs and spaces)
def example_function():
    if condition:
    print("Using tabs")
    else:
        print("Using spaces")

So, if you’re like I was and have struggled with this before or still struggling with it right now, take the extra time to double-check your formatting. It’s a simple step that can save you from a lot of frustration later.

Pay attention to the existing code and stick to he code formatting standards in your company and repo.

#2. Adding unnecessary comments/codes

Comments can come in being handy but having too much just clutters the code. In my early days of coding, I was also guilty of this, I believed that the more comments I added, the better my work would be. It was as if explaining every single line of code would make it easier for others to understand my work, at least that's what I believed. I also had to use commented-out codes leaving chunks of it in my project, thinking What if I need this later? or It’s better to keep it here just in case. But honestly, that approach always caused more harm than good.

Commented-out codes clutters the file and makes it harder for others (and even me) to follow the logic of what’s actually being used. It sends a confusing message — should this code stay? Is it still relevant? I’ve had pull requests rejected because my code was littered with comments that added little value. Instead of making my work clearer, it overwhelmed reviewers and some had to call me out on this during pull requests, and I can’t blame them.

Now, I’ve made it a habit: if the code/comment isn’t needed, I delete it. I only add them when they truly enhance understanding—like explaining complex logic or providing context that the code itself can’t convey. If the code is clear and self-explanatory, I let it speak for itself. Peradventure, if there’s any part of it that might be useful later, I move it to a draft file or version control where it can be easily retrieved. This keeps my codebase clean and reduces unnecessary distractions for anyone reading or reviewing my code.

It took me some time to let go of the “just in case” mindset, but trust me — cleaning up unnecessary code makes a your codes far more clear, easier to read and satisfying to review.

Looking back right now, I realize that over-commenting was my way of compensating for insecurity about my code. But good code is concise, clean, and self-documenting. It doesn’t need a lot of hand-holding. Learning to strike that balance made my work to be more professional and easier to collaborate on.

#3. Left-over logs

Logs are incredibly helpful debugging and testing but are not needed in production so can you leave them out of your PRs. Thinking that they were all part of the debugging process, I would always leave log statement scattered through out my codes. Logs were handy for tracking down issues during development and testing, but I didn’t realize how much of a mess they could make when it came time to submit a pull request.

However, leaving leftover logs in your code is a surefire way to get your pull request rejected. These logs don’t belong in production. They clutter the code, slow down the application, and can even expose sensitive information if left unchecked.

What you should do to prevent this log statements from logging you out of better code reviews, is to develop an habit of removing all unnecessary log statements before submitting your PRs. If maybe you need to keep track of something for later debugging, you should add it in a way that can be easily disabled or ensure it’s only available in development environments. You should also learn to use more sophisticated debugging tools that don’t rely on leaving logs behind in the codebase.

This small step can make your code cleaner, safer, and looks more professional — and it’s one you should always double-check before hitting submit.

#4. Submitting Incomplete changes

Submitting incomplete work, thinking you could “fix it later” or “making adjustments during the review process” is what sounds good at 11:59 PM the night before a deadline, but feels like a terrible decision the next morning when you're frantically trying to explain to your reviewers why key sections are missing or half-baked. This approach does mothing more than wasting everyone’s time and yours too - the reviewers’, and the team’s. It's like ordering takeout and telling yourself you'll eat just half now and save the rest for tomorrow – we all know how that usually ends. The future you always ends up dealing with the consequences of present you's optimism.

One thing that I have been able to garner from experience is the idea of ensuring that the changes being submitted in the pull requests are ready for production. This kind of changes lead to confusion. They also ease the reviewer’s task in not fully comprehending the range of what you are trying to accomplish. More dangerous they can bring about instability if merged by mistake. I am absolutely guilty of submitting PRs which are not quite ready in the past, and on the receiving side it is not fun as well.

These days, I ensure that each PR I submit is ready for production. That means verifying the changes I made meet the project’s quality and then adding all the requisite alterations such as documentation, tests, and configurations. If a piece of work is unable to go into production, then it cannot simultaneously proceed into the evaluation stage.

This mindset has helped me work more efficiently and gain the trust of my team. Reviews are smoother, and the feedback I receive is more focused and actionable. It’s a simple change in approach, but it’s made a big difference in how I contribute to projects.

#5. Breaking changes

There are always some developers who are not aware of the ramification of incorporating elements that could prove destructive to a flow. I can't blame them. Even for me, I had believed that, If a new feature works on my code, what’s the big deal? But then I saw how breaking changes can cause havoc for all of those relying on that code base.

For instance, I remember once submitting a pull request to my reviewer that unintentionally broke a critical feature. It wasn’t fun explaining to the team why their previously working code no longer functioned as expected. I knew from that day that it is as important what changes others are going through are and how those changes affect them. I starting thinking beyond my own changes and consider the bigger picture.

What I should have done was to address every change I encountered with caution, making sure that my codes were thoroughly tested to ascertain that I am not destroying any functionality or feature, and that I was deliberate about backward compatibility. However, where it is inevitable, I ensure I give vivid hints on the breaking change and perhaps offer a way forward that may enable affected areas to easily make the necessary adjustments.

#6. Including unrelated changes into the PR

Including unrelated changes in a single pull request is another mistake developers make similar to adding unnecessary comments & codes. At the time, you won’t see the problem—you'll have the thought of making a few extra tweaks while you're at it?

A similar situation was with my team last week, an intern made a pull request and it had a bug fix, a small change in the UI, and a new feature. The review-lead called her out on it, and rightfully so because it made the PR harder to review, testing became more complicated and merging it even riskier.

What do you suppose she would have done differently? She should have kept her PR focused. Every PR is focused on a specific goal or on a number of related modifications. If she was dealing with something unrelated that requires attention, then she should have taken it down and write another PR about it at another time.

Doing all this does not only makes reviews quicker and more effective but also helps maintain a clean and organized codebase. It’s not just okay to write good code — it’s more about making life easier for the team that'll be reviewing and using it as well.

#7. Letting the reviewer figure things out themselves

Another mistake common among coders is assuming that their work would speak for itself. They will submit a pull request without providing much explanation, thinking we (the reviewer) should just “figure it out.” More often than not they fail to know that they are only complicating matters in their workplace and even slowing down progress.

This is the random PR I was paged to review at around 0600 on GitHub. The developer made a set of changes and sent a PR request with all of them described in the commit, but no description of what changes have been made. I replied with a list of questions asking him to clarify what he'd done and why. That back-and-forth could have been avoided if he had simply taken the time to provide an overview upfront.

Hey guys, get it right we are just code reviewers not mind readers here bro! 😠😡

When making a pull request, you are supposed to include a clear description with it. Explain the purpose of the changes, provide details as to why the changes were made, where they are in relation to the bigger picture, all the information that the reviewer should be mindful of. If there are specific areas you would like to be commented on, please mention them here. This not only speed up the review process but also saves a fair amount of time for the reviews while simultaneously giving the reviewers confidence knowing that you value their time. Believe me, this is one habit that will pay you a lot of benefits to be in a position to practice.

#8. Infrequent and large pull requests

I was technically laughing at myself😂 while typing this on my computer because I had so much problem with this mistake. When I first started working on collaborative projects, I had this habit of submitting infrequent and large pull requests. I’d spend days (sometimes weeks) working on a feature, only to push everything at once in one massive PR. I thought I was being efficient by getting all the work done before submitting it. I was wrong.

Reviewing those large pull requests turned out to be a headache - for me and my reviewers. The sheer size made it hard to spot issues, whether it was incorrect logic, breaking changes, or even simple oversights. More than once, I ended up having to rework large portions of my code because feedback came too late in the process.

Small, frequent pull requests are easier to review, easier to test, and much faster to merge. It is, in fact, a habit I wish I had adopted sooner. Now, I have understood the effectiveness of doing many small pull requests often. I work in segments because my reviewers have less work to do than if I presented them the entire manuscript all at once. It also lets me notice errors before they end up on the page, or apply changes incrementally rather than in bulk. Thus, I can out rightly say that this shift in approach has not only enhanced the quality of my work but also enhanced me as a better and consistent collaborator.

#9. Not writing proper commit messages

The solution to this issue is simple. Using Conventional commits. I even used them while working on different projects, they definitively help. However, before proceeding, let's first talk about this.

Of course, if you're like me, then, you didn’t care much about learning how to write good commit messages because you considered it unimportant, or for whatever reason never even thought about it at all. When the time comes for you to write commits, you would write generic messages such as “commit 1” or “changed stuff,” thinking they were just a formality. Yeah, that was the person I was indeed.

Flashback to when I was troubleshooting an issue within a project that I had done. Looking back at my commits again, I saw my mistake: I had ended up providing myself with no hints. Each commit was a nightmare written as codes, and piecing everything together took far longer than it should have. That experience taught me the value of writing clear and descriptive commit messages.

Conventional Commits provides a structured, consistent way to describe changes, making it easier to understand what each commit does at a glance.

For example, instead of “fixed bug”, You should write something like "fix: resolve null pointer exception in user auth module." It’s like a small tweak in text editor to get rid of unwanted symbols, but when you’re trying to review colleague’s code or yourself after a couple of weeks or months, it’s a godsend.

To make it even easier, you can automate this process when working on your project. Tools like commitlint help enforce standards, ensuring every commit message follows the convention. This tool works like Prettier but only for committing, It has saved me, or more so, my team a significant amount of time and effort. Intelligible commit messages may sound like a triviality but they are in fact the key to successful collaboration and a project’s sustainability.

Guidelines for Writing Pull Request That Is Easily Reviewed

If we're to briefly talk about why your PR was encountered issues, majority of the replies would be centered around the fact that your pull requests were too big, too messy, and that was why everyone hated reviewing them. See what Sindre Sorhus, a full time open-source and app maker with tons of experiences reviewing codes.

While writing about the mistakes, you'll notice that almost all of them required a mindset shift. Changing your mindset is the first thing to do. The next is to put in the work (take action) to be better. In order to make PRs that your team would loves to review (and actually get merged fast), let's read further to see the kind of actions and efforts you need to put in:

#1. Keep it short

There are many advantages attached to why you should keep your pull requests focused and short. Keeping PRs short allows the review to give it its undivided attention and analyze the changes faster.

Big PRs = Big Headaches, So break your work into smaller, manageable chunks. This is a simple formula I use to explain this.

Here’s my golden rule: one feature per PR. It keeps the scope focused and makes it easier for others to understand the changes.

And I avoid “drive-by” refactors—they might feel tempting, but they can easily bloat a PR with unrelated changes. No one wants to sift through 1,000+ lines of code in one sitting. The generally recommended number of lines of code (LOC) for a pull request is 200-400.The longer your PR, the more time it takes to review it and give feedback.

Smaller PRs aren’t just considerate; they’re efficient. Everyone wins. However, writing short PRs is easier said than done. Pull requests can quickly increase in length after tests are written for it, for example. It takes practice and a plan to keep them concise but thorough enough to provide context.

Instead of counting LOC, some teams create shorter pull requests by breaking them down into units like database layer or event publisher. Experiment with various methods for keeping PRs short and adopt whatever system works best for you and your team.

#2. Start with a solid title

I’ve come to appreciate the importance of starting with a solid title for pull requests (PRs). A good title is more than just a label—it sets the tone for the entire review process. I always aim to keep mine short and clear.

For example, “Add user profile editing” instantly tells reviewers what to expect. On the other hand, vague titles like “Small updates” leave people guessing, which can slow things down. If your reviewer does not know what problem you are trying to solve with your code changes, they won’t know whether you’ve succeeded in addressing and solving it.

A clear title makes it easy for someone to understand the PR’s purpose at a glance, and that’s a win for the whole team. The title should describe what the problem it solves, not how it's implemented. I get a lot of PRs with titles like "Adds string handling logic" where it should have been "Fix foo() incorrectly throwing when receiving a string" (Also notice the different tense).

#3. Write a descriptive summary

When writing a PR summary, the first and overriding concern should be to make things as clear and as complete as possible. Your descriptive summary should briefly state:

• What this PR does:

For example, state the feature or fix that will be introduced. Make your language simple and relatable so that the reviewer would not find it hard to understand.

• Why its needed:

State why it is necessary, or it fixes a bug, improves something or makes the user interface better, etc.

• How it works:

If how it works isn't immediately obvious, make sure to explain it in a simple way how it works. Thus, when working on UI-related changes, it helps a lot to add screenshots or GIFs. It makes it easier for the reviewers to have a visual sense of the design and also save time on a lot of questions.

#4. Use commit messages wisely

Writing clear commit messages are like Christmas presents we give to ourselves (maybe our future self) and everyone else working on the codebase because writing meaningful commits saves us the frustration of revisiting unclear commits later on. A little effort now saves me (and my team) a lot of headaches later. It’s a small habit that makes a big difference.

Well, ensure that each commit you include should tell a story of what changed and why it matters. For example, “Fix login bug by adjusting token validation” instantly explains the problem and the solution. Compare that to something vague like “Fix stuff,” which leaves you guessing months down the line.

For example, your commit messages should complete the sentence "when this commit is applied, it will... ." Forces a certain tense and forces thinking about "what" and "why" rather than "how"

#5. Review your own code first

Before hitting "Create PR," make it a point to re-read your changes thoroughly. This is something that you desire to be perceived as a person who respects his reviewers’ time as well as someone who takes pride in their craft and, therefore delivers work of beyond reasonable quality. It's like double-checking an important email before hitting send – those extra few minutes of self-review can save hours of back-and-forth and prevent unnecessary drive-by refactoring and code fixes.

Ask yourself these questions:

• Does this logic make sense?

• Are there loose console logs lying around the code?

• Is the code clean and readable?

• Is the code cluttered or not?

• Should I refactor this function?

Pausing to self-reflect also allows for catching glaring obtrusive errors, not to mention it gives you time to make your work more polished before it is seen by others. I have witnessed reviewers provide invaluable feedback and even clean up messy codes and that should not be. To make the process easier and more efficient for everyone involved, you do the code reviews for yourself first.

#6. Tag the right people

When tagging reviewers for a PR, be intentional about involving the right people. Avoid spamming the entire team and instead focus on those who are familiar with the codebase or directly relevant to the feature.

This approach has helped a lot of developers get faster, more actionable feedback. It also shows respect for everyone’s time—there’s no need to involve someone who won’t add value to the review. If you tag the right people, it is ensured that the process stays efficient and collaborative.

#7. Explain tricky parts

Personally, when I am aware that a certain part of my code might be tricky or non-obvious, I make it a priority to add comments or explanations in the PR. For instance, if I have come up with a really complex regular expression for the validation of an email, I will put a comment such as the following, “This regex takes care of special cases for email validation.”

I’ve realized it’s unfair to make my reviewers play detective. And so, providing context upfront saves their time and reduces confusion. Plus, it creates possibilities for receiving more feedback because in this case, the reviewers would not spend time trying to predict the meaning of certain events, but rather can concentrate on understanding the logic rather than trying to decipher what's happening. It is one of the easiest things that any coder can be advised to do when it comes to making reviews less tedious.

#8. Be polite in replies

When responding to feedbacks on your PRs, ensure to be polite and open-minded. For instance, if a reviewer has noted something or pointed out an issue that'll be problematic, you just say, “Well done!” Glad you like it, I’ll fix that,” instead of saying “Oh no you are wrong!”

The analysis of the two approaches shows that being respectful enhances a positive morale and enthusiasm. It illustrates that the reader’s view is important and their intention to contribute to the correction of a person is appreciated, even if you don’t always agree. Code reviews are a team effort, and maintaining politeness helps build trust and keeps the process productive for everyone involved.

#9. Include tests in your PR

This is the one rule I live by when it comes to submitting or reviewing Pull Requests (PRs): always include tests. If I could offer just one tip to improve the quality of PRs, it’s this.

Let me paint a picture for you. Have you ever been overwhelmed with work, only to receive a PR that makes significant changes to the codebase—without any tests? I have, many times. And my first reaction is always the same: "Could you add some tests to show this change actually works?"

You see, when a developer makes a PR with no tests, then you get work friction, unnecessarily so. That is why, when considering a PR with a similar system, I have to go through great lengths to reverse engineer it, find glitches, and discover all the things that it relies on, that may fail. It will be like receiving a puzzle with missing pieces and then being expected to verify if the image is correct.

Here’s an example: I once received a PR that completely overhauled a critical part of our system. It was a complex change, but the contributor hadn’t included any tests. He explained that he was “too busy” and wanted my input first. Reviewing it felt like walking into a dark room and trying to rearrange the furniture—I was bound to miss something. If they had just written tests, it would have saved both of us time and effort.

Of course, I understand that at times you may be uncertain of how you are handling a particular feature and would like commit before committing the time to writing tests. That's fine, but there are far much effective ways of doing so. For instance, why not ask for a quick pair coding session or an informal code review? These approaches can allow for real-time feedback without placing the burden of testing entirely on the reviewer.

This is why when writing a PR, I ensure that I include many tests. But I do not stop at the happy path—I add negative test cases to make sure my code respond as expected during failure. These tests are my way of making sure people understand that I have a plan and that I’ve tried it on a game and it works. Personally, I find that taking the time to write out tests on paper can identify poor design or a logical error with code before even someone else has a chance to review the code.

Beyond proving that the code works, tests are invaluable for documentation. They tell the reviewer exactly what I’m trying to achieve and why I believe my changes are correct. A well-written test can be more persuasive than a paragraph of explanation because it shows, rather than tells.

Whenever I open a PR, the most common thing that I do is to ensure that proper tests are done. But I do not only run the simplest way — I submit negative test to make sure the code runs exactly how it should even if things get a little tricky. For me, these tests pragmatically meant, oh, they are getting ready, they have thought it through, they have tried it and let me show you the proof. For some reason, my writing tends to alert me to bugs or flaws in my logic before anyone else does – even before they see the code.

Unlike simple demonstrations that the code performs the appropriate function or set of functions, tests are incredibly useful for documenting the code. Seems like they immediately instruct the reviewer on what I am doing and why I think my changes are right. Often, a test is more convincing than even a piece of descriptive prose can be because it demonstrates rather than states.

It is worth noting that while tests show that the code is workable, they are even more important as documentation. It lets the reviewer know right off what I’m after and why I think my changes make sense. When the test is well written, it speaks a thousand words more than the best written paragraph of argument.

Here’s another scenario: imagine someone submits a PR that introduces a new feature, but you can’t figure out what problem it solves. Without tests, you’re left guessing. But with tests, it becomes clear—they show what the code does and, often, why it matters.

Including tests isn’t just about making life easier for the reviewer; it’s also builds up confidence in your work. When I submit a PR with thorough tests, I know I’ve done my due diligence. I’ve anticipated potential questions and concerns. And more often than not, the review process is smoother and faster because of it.

So, the next time you’re working on a PR, remember this: write the tests. They’re not just a nice-to-have—they’re the backbone of a good PR. They save time, reduce misunderstandings, and ultimately, they make your contribution stronger.

#10. Close the loop:

For most people, one could say a PR isn’t truly done until the loop is closed. As a result, it is recommended to synchronize the references to the merged branches after their merge and remove the branches that were used in the merge. Many times it is just a minor action that ensures that the code base or the documentation remains clean and everyone involved in the project receives updated information.

Skipping this step can create confusion or clutter down the line, which is why this should be made a habit. You should know better than thinking that closing the loop is just about wrapping things up. No it isn't. It’s more about setting the stage for smoother collaboration moving forward.

Conclusion

First, let’s admit it: reviewing pull requests is really hard as well as writing codes that wouldn't in one way or the other fall into the category of the mistakes we've talked about. As a reviewer, it’s your responsibility to make sure that the code is correct and of high quality before it gets merged into master.

You are expected to do that by looking at a Git diff and list of files changed. You have to understand what the pull request is trying to achieve, what approach is being taken, what’s going on, and how all these files fit together — enough that you could potentially suggest an improvement. You may have to be on the lookout for typos or style problems. That’s a LOT of stuff a reviewer needs to do, especially in a large pull request!

I don't know about you but I love the feeling of getting to hit the merge button on my code and sending it off to production. That's our ultimate goal as software engineers - to get our code out there into the world. However, unless you're living life on the edge, there's a big hurdle to overcome before getting to push that merge button - getting approvals on your pull request. Let's talk about how to make the best of your PRs that way your reviewers know exactly what they're looking at and you get to hit that merge button faster.

Pull requests are telling the story of your changes. They are a conversation between you and your reviewers and as the author of the story you want to make sure the process of reviewing your PR is as easy as possible. It is vital that our PRs give everything to our reviewers that they may need. They should concisely describe our motives and thoughts behind our changes all the while preemptively answering any questions our reviewers may have.

Writing pull requests is both an art and a science. Throughout this article, we've explored the common pitfalls that can derail your PR reviews and outlined the key practices that can make them more effective. From avoiding unnecessarily large PRs to writing clear commit messages, and from maintaining consistent formatting to providing thorough documentation, each aspect plays a crucial role in creating pull requests that your team will appreciate.

Remember that a well-crafted pull request makes easy code reviews and also ensures that the pull request fulfils the reason of its creation.