Why is my merge request ignored? Ways to make your code cleaner and faster to review
Every developer has been there: you submit a merge request, confident in your implementation, only to watch it sit in limbo for days or weeks. Meanwhile, your teammate's smaller change gets approved and merged within hours. The difference often isn't the quality of the code—it's how well the change is presented to reviewers.
Code review is fundamentally a communication challenge. Your job isn't just to write working code; it's to communicate your changes clearly enough that reviewers can understand, validate, and approve them efficiently. Here's how to make your merge requests irresistible to reviewers.
The Psychology of Code Review
Before diving into tactics, understand what reviewers are thinking when they see your merge request in their queue. They're likely already context-switching from their own work, possibly reviewing multiple changes, and definitely pressed for time.
When reviewers see a large, poorly described change, their instinct is often to defer it for "when they have more time"—which may never come.
The Reviewer's Mental Model
Reviewers ask themselves three questions, in order:
- What is this change trying to accomplish? (Purpose)
- How does this change accomplish it? (Approach)
- Is this change implemented correctly? (Implementation)
If they can't answer the first question quickly, they'll often skip your merge request entirely.
Start with the Story: Writing Effective Descriptions
Your merge request description is your elevator pitch. It should tell a complete story that makes the reviewer want to understand your solution.
The Perfect Description Template
## Problem
Brief explanation of what was broken or missing
## Solution
High-level approach to solving the problem
## Changes
- Bulleted list of specific changes made
- Focus on the "what" not the "how"
## Testing
How this was verified to work
## Risks/Considerations
Any potential issues or trade-offs
Here's a real example:
## Problem
Users can't recover their accounts when they forget both their password and security question answers, leading to support tickets and user frustration.
## Solution
Add alternative recovery method using email verification with temporary recovery codes.
## Changes
- Add recovery code generation and validation
- Create email template for recovery codes
- Add new recovery flow to login page
- Update user model to track recovery attempts
## Testing
- Manual testing with multiple email providers
- Added unit tests for code generation/validation
- Tested rate limiting and expiration
## Risks/Considerations
- Recovery codes are single-use and expire after 1 hour
- Rate limited to 3 attempts per hour per user
Size Matters: The Goldilocks Principle
Large merge requests are review killers. The optimal size depends on your team and codebase, but general guidelines apply:
Sweet Spot Metrics
- 150-400 lines of changes: Large enough to be meaningful, small enough to review thoroughly
- Single logical change: One feature, one bug fix, one refactor
- Reviewable in 15-30 minutes: Fits into a reviewer's schedule break
Breaking Down Large Changes
Instead of this monolithic approach:
feat: Complete user dashboard redesign (2,847 lines changed)
- New dashboard layout
- Updated user profile page
- Refactored authentication
- Added analytics tracking
- Updated tests
Break it into focused changes:
1. refactor: Extract authentication utilities (127 lines)
2. feat: Add analytics tracking infrastructure (89 lines)
3. feat: New dashboard layout components (234 lines)
4. feat: Updated user profile page (198 lines)
5. test: Update dashboard tests for new layout (156 lines)
Each change builds on the previous ones and can be reviewed independently.
Code Organization: Guiding the Review Journey
Structure your changes to tell a story. The order of files in your diff matters because it controls the reviewer's journey through your code.
Optimal File Order
- Tests first: Shows what behavior you're implementing
- Interfaces/types: Establishes contracts
- Core logic: The main implementation
- Integration points: How it connects to existing code
- Documentation: README updates, comments
Example of Good Organization
📁 Changes (8 files):
├── tests/user-recovery.test.js (+45, -0) ← Shows intended behavior
├── types/recovery.d.ts (+12, -0) ← Defines contracts
├── services/recovery-service.js (+89, -0) ← Core implementation
├── controllers/auth-controller.js (+23, -5) ← Integration point
├── templates/recovery-email.html (+15, -0) ← Supporting files
├── routes/auth-routes.js (+8, -0) ← Configuration
├── migrations/add-recovery-fields.sql (+12, -0) ← Database changes
└── README.md (+6, -0) ← Documentation
This organization lets reviewers understand your approach before diving into implementation details.
Code Quality: Making Review Effortless
Clean, readable code reduces cognitive load on reviewers and speeds up the process.
Self-Documenting Code
Instead of relying on comments to explain what code does:
// Bad: Needs comments to understand
function calc(u, days) {
// Calculate base rate
const base = u.plan === 'premium' ? 0.15 : 0.10;
// Apply time discount
const discount = days > 30 ? 0.05 : 0;
return (u.usage * base) - (u.usage * base * discount);
}
Write code that explains itself:
// Good: Self-documenting
function calculateUsageCost(user, billingPeriodDays) {
const baseRatePerUnit = user.plan === 'premium' ? 0.15 : 0.10;
const longTermDiscount = billingPeriodDays > 30 ? 0.05 : 0;
const baseCost = user.usage * baseRatePerUnit;
const discountAmount = baseCost * longTermDiscount;
return baseCost - discountAmount;
}
Consistent Patterns
Use established patterns from your codebase. If your team uses specific error handling, validation approaches, or architectural patterns, follow them consistently.
Consistency reduces the mental overhead for reviewers.
Tests as Documentation
Well-written tests are some of the best documentation you can provide. They show exactly what behavior you're implementing and provide confidence that your changes work correctly.
Test Structure That Tells a Story
describe('User Account Recovery', () => {
describe('when user requests recovery code', () => {
it('sends recovery code to verified email', async () => {
const user = await createUser({ email: 'test@example.com' });
await requestRecoveryCode(user.email);
expect(emailService.send).toHaveBeenCalledWith({
to: 'test@example.com',
template: 'recovery-code',
data: { code: expect.stringMatching(/^\d{6}$/) }
});
});
it('rate limits to 3 attempts per hour', async () => {
const user = await createUser();
// Make 3 successful requests
await requestRecoveryCode(user.email);
await requestRecoveryCode(user.email);
await requestRecoveryCode(user.email);
// 4th request should be rejected
await expect(requestRecoveryCode(user.email))
.rejects.toThrow('Rate limit exceeded');
});
});
});
These tests clearly communicate the intended behavior without requiring reviewers to decipher implementation details.
Addressing Feedback Gracefully
How you handle review feedback significantly impacts how quickly future merge requests get reviewed.
Responding to Feedback
- Acknowledge quickly: Even if you can't fix it immediately
- Ask clarifying questions: If feedback isn't clear
- Explain your reasoning: When you disagree, but respectfully
- Make requested changes: Don't argue about style preferences
- Thank reviewers: Even for critical feedback
Example of Good Feedback Response
> Consider extracting this validation logic into a separate function
Good point! I extracted it into `validateRecoveryRequest()` in commit abc123.
This also makes it easier to test the validation separately.
> This error message might be confusing to users
You're right. I updated it to be more specific about what went wrong.
The new message is: "Recovery code has expired. Please request a new one."
This approach shows that you value the reviewer's input and take their suggestions seriously.
Advanced Techniques
Draft Merge Requests for Early Feedback
Use draft/WIP merge requests to get architectural feedback before implementing everything:
## 🚧 DRAFT: User Account Recovery Implementation
### Approach
Planning to implement recovery using temporary codes sent via email.
### Questions for reviewers:
1. Should codes expire after 1 hour or 24 hours?
2. Rate limiting at 3 attempts/hour or 5 attempts/hour?
3. Should we track recovery attempts in audit logs?
### TODO:
- [ ] Implement code generation
- [ ] Add email templates
- [ ] Write tests
- [ ] Update documentation
Stack Dependencies Clearly
When merge requests depend on each other, make the relationship explicit:
## Dependencies
This PR depends on #123 (authentication refactor) being merged first.
## Testing
To test locally:
1. Checkout and merge PR #123
2. Apply this branch
3. Run integration tests
Clear dependencies help reviewers understand the context and review order.
Building Review Culture
The best way to get good reviews is to give good reviews. When you review others' code:
- Review promptly: Treat others' merge requests as you want yours treated
- Be constructive: Suggest improvements, don't just point out problems
- Ask questions: "Could you help me understand why..." instead of "This is wrong"
- Acknowledge good work: Point out clever solutions or clean implementations
Conclusion
Getting your merge requests reviewed quickly isn't about gaming the system—it's about respecting your reviewers' time and cognitive load. When you make your changes easy to understand and review, everyone benefits: reviewers can do thorough reviews efficiently, and your code gets merged faster with fewer back-and-forth cycles.
Remember that code review is a collaborative process. The goal isn't just to get your code approved; it's to improve the codebase, share knowledge, and maintain quality standards. By focusing on clear communication, appropriate sizing, and respectful collaboration, you'll find your merge requests moving through the review process much more smoothly.
Treat every merge request as an opportunity to demonstrate not just your technical skills, but your ability to work effectively with your team.