Small Pull Requests, Big Impact: Mastering the Art of Incremental Refactoring

How Tiny PRs Can Revolutionize Code Quality and Team Efficiency

June 23, 2024

Introduction

Refactoring is crucial in software development. It involves improving the internal structure of code without altering its external behavior, enhancing readability, reducing complexity, and maintaining functionality. However, large-scale refactoring can be risky and overwhelming if not managed incrementally. This post demonstrates how small, frequent pull requests (PRs) can make refactoring more effective and efficient, using a real-world example from a Laravel project.

The Need for Incremental Refactoring

Refactoring Challenges

Refactoring large sections of code can be daunting, especially if done in one go. Large PRs often become cumbersome to review and can introduce bugs if not handled carefully. Breaking down tasks into smaller PRs simplifies the process, making reviews easier and reducing the risk of errors.

The Incremental Approach

Breaking down refactoring tasks into smaller PRs helps manage complexity, facilitates easier reviews, and improves code quality. Think of it as making consistent, small improvements rather than a single massive overhaul.

A Real-Life Example: Refactoring a User Management System in Laravel

Let’s explore how incremental refactoring can be applied in a Laravel-based user management system.

Initial Codebase

Consider the following simplified code for managing users in a Laravel application:

// app/Http/Controllers/UserController.php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\User;

class UserController extends Controller
{
    public function store(Request $request)
    {
        $validated = $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
            'password' => 'required|string|min:6',
        ]);

        $user = User::create([
            'name' => $validated['name'],
            'email' => $validated['email'],
            'password' => bcrypt($validated['password']),
        ]);

        return response()->json($user, 201);
    }

    public function show($id)
    {
        $user = User::find($id);
        if (!$user) {
            return response()->json(['error' => 'User not found'], 404);
        }
        return response()->json($user);
    }

    public function update(Request $request, $id)
    {
        $user = User::find($id);
        if (!$user) {
            return response()->json(['error' => 'User not found'], 404);
        }

        $validated = $request->validate([
            'name' => 'sometimes|string|max:255',
            'email' => 'sometimes|email|unique:users,email,' . $user->id,
            'password' => 'sometimes|string|min:6',
        ]);

        $user->update($validated);

        return response()->json($user);
    }
}

Step 1: Refactor Email Validation

Start by refactoring the email validation logic into a custom request. Create a new branch (refactor-email-validation) for this change.

// app/Http/Requests/StoreUserRequest.php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    public function rules()
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
            'password' => 'required|string|min:6',
        ];
    }
}

Update the store method to use this new request.

// app/Http/Controllers/UserController.php

namespace App\Http\Controllers;

use App\Http\Requests\StoreUserRequest;
use App\Models\User;

class UserController extends Controller
{
    public function store(StoreUserRequest $request)
    {
        $user = User::create([
            'name' => $request->validated()['name'],
            'email' => $request->validated()['email'],
            'password' => bcrypt($request->validated()['password']),
        ]);

        return response()->json($user, 201);
    }
    // ...
}

Submit this change as a small PR, focusing solely on the refactoring of the email validation logic.

Step 2: Refactor User Creation Logic

Next, move the user creation logic into a separate service. Create another branch (refactor-user-creation) from the main branch and implement the changes.

// app/Services/UserService.php

namespace App\Services;

use App\Models\User;

class UserService
{
    public function createUser(array $data)
    {
        return User::create([
            'name' => $data['name'],
            'email' => $data['email'],
            'password' => bcrypt($data['password']),
        ]);
    }
}

Update the store method to use this new service.

// app/Http/Controllers/UserController.php

namespace App\Http\Controllers;

use App\Http\Requests\StoreUserRequest;
use App\Services\UserService;

class UserController extends Controller
{
    protected $userService;

    public function __construct(UserService $userService)
    {
        $this->userService = $userService;
    }

    public function store(StoreUserRequest $request)
    {
        $user = $this->userService->createUser($request->validated());

        return response()->json($user, 201);
    }
    // ...
}

Submit this change as a new PR, focusing on moving the user creation logic into a dedicated service.

Step 3: Refactor User Update Logic

Similarly, refactor the user update logic into the same service or another relevant service. Create a new branch (refactor-user-update) and refactor accordingly.

// app/Services/UserService.php

namespace App\Services;

use App\Models\User;

class UserService
{
    // ...
    public function updateUser(User $user, array $data)
    {
        if (isset($data['password'])) {
            $data['password'] = bcrypt($data['password']);
        }
        $user->update($data);
        return $user;
    }
}

Update the update method in the controller to use this service.

// app/Http/Controllers/UserController.php

namespace App\Http\Controllers;

use App\Http\Requests\UpdateUserRequest;
use App\Services\UserService;
use App\Models\User;

class UserController extends Controller
{
    // ...
    public function update(UpdateUserRequest $request, $id)
    {
        $user = User::find($id);
        if (!$user) {
            return response()->json(['error' => 'User not found'], 404);
        }

        $updatedUser = $this->userService->updateUser($user, $request->validated());

        return response()->json($updatedUser);
    }
    // ...
}

Submit this as a small PR, focusing on refactoring the update logic.

Handling Overlapping Changes

In practice, you may encounter overlapping changes or need to update previous PRs. Here's how to manage it:

Example Scenario: Adjusting Validation Logic

Suppose you realize that the password validation logic needs to include a complexity requirement after the initial refactor. Here's how to manage it:

1. Create a New Branch:

Create a new branch (adjust-password-validation) from the branch where the initial validation was refactored (refactor-email-validation).

2. Update the Logic:

Add the complexity check in the StoreUserRequest.

// app/Http/Requests/StoreUserRequest.php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    public function rules()
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
            'password' => 'required|string|min:6|regex:/[A-Z]/',
        ];
    }
}

3. Submit and Rebase:

Submit this as a new PR. Once refactor-email-validation is merged, rebase refactor-user-creation with the main branch, incorporating the updated validation seamlessly.

Benefits of Small PRs

1. Enhanced Reviewability

Smaller PRs are easier to review. Reviewers can focus on specific changes without being overwhelmed by a massive amount of code. This leads to more thorough and accurate reviews, catching potential issues early.

2. Faster Integration

With smaller PRs, feedback is provided more quickly. This accelerates the review process, allowing changes to be integrated faster and reducing the time that PRs remain open.

3. Reduced Risk

Incremental changes reduce the risk of introducing new bugs. Each PR is limited in scope, making it easier to identify and fix issues. This approach also facilitates more effective use of automated testing.

4. Continuous Improvement

Small, frequent PRs encourage a culture of continuous improvement. Developers can tackle technical debt incrementally, making the codebase cleaner and more maintainable over time.

Best Practices for Implementing Small PRs

1. Define Clear Goals

Each PR should have a clear, singular goal. Whether it's refactoring a component, updating a function, or improving performance, define what the PR aims to achieve

and stick to it.

2. Communicate Effectively

Provide detailed descriptions for each PR. Explain what changes were made, why they were necessary, and how they were implemented. This context helps reviewers understand the purpose and impact of the changes.

3. Write Tests

Include relevant tests for each PR. Even minor changes benefit from tests that verify functionality and prevent regressions. This practice ensures that each incremental change maintains or improves code quality.

4. Encourage Timely Reviews

Promote a culture of regular and timely reviews within your team. Smaller PRs are less burdensome to review quickly, fostering an environment of continuous feedback and collaboration.

5. Leverage Automation

Utilize automated tools for code analysis, testing, and integration. Automated checks can catch common issues, allowing reviewers to focus on more nuanced aspects of the code. This enhances the efficiency and reliability of the review process.

Conclusion

Embracing the power of small PRs can transform your approach to refactoring. By focusing on incremental changes, you manage complexity, reduce risk, and enhance code quality. This approach promotes continuous improvement and keeps your development process agile and responsive. Start small, think big, and watch how little PRs can lead to mighty refactors, revolutionizing your codebase and boosting your team's efficiency.

Final Thoughts

Additional Benefits: Smaller PRs can also improve team morale by reducing the stress associated with large, complex changes and facilitating more manageable reviews.

Tools and Resources: Consider tools like GitHub’s code review features, static analysis tools, and CI/CD pipelines to automate and streamline the process of managing small PRs.

Your Next Steps: Implement small PRs in your next refactoring task and observe the difference it makes. Share your experiences with your team and refine your approach based on collective feedback.

Happy refactoring!

THAKURCODER BLOG