Critical Path Newsletter

The patch a day principle

I met with Ovidiu this week, a new developer in our Romanian office, for his first week training.

“Once you start development,” I said, “you submit one patch a day.”

Silence on the other end of the phone—a common response from any new team member. Ovidiu’s English is great, but I could have been speaking a different language.

"You've heard of test-driven development and pair programming,” I said. “Patch a day may be a stronger agile process."

A patch is a small, self-contained, portable file containing new code a developer wants to add to source control. It might be a new function, a bug fix, or the skeleton of a new class.

When a developer submits code to source control, he generates a .patch file, a text-based file listing lines of code added, deleted, and modified that can be used to revert or re-apply the changes. It’s portable, letting other developers apply it to their local code.

Index: comp/ajax/signup_user_prepare.php
==============================================
@@ -14,18 +14,48 @@
   if (isset($_REQUEST['vl_id'])){
    
-    $sm->assign("vl_id", $_REQUEST['vl_id']);
-    $sm->assign("ta", $_REQUEST['ta']);
-    //$content = $sm->fetch("signup_ajax.htm");
-
-    $content = $sm->fetch("signup_ajax_player.htm");
+    $sm->assign("vl_id", $_REQUEST['vl_id']);
+    $sm->assign("ta", $_REQUEST['ta']);
+
+    $content = $sm->fetch("signup_ajax_player.htm"); 

Source control systems like CVS and Subversion generate .patch files. Others generate similar files.

Why not commit the code directly to source control?

In Macadamian's process, we keep the code in source control 100% functional. At any moment, a customer could request a working version, a tester could request the latest fixed version, or we might receive a request for an update. Team members must always have access to working code. Nightly automated unit tests must all pass on the integration server. Broken source control is a bottleneck.

Instead of submitting directly to source control, patches go through code review. The process works like this...

A developer sends an e-mail to the project mailing list, containing:

• the patch file (attached)
• an explanation of the changes
• the name of the peer reviewer

The reviewer and developer discuss the code on the mailing list, refining it as necessary.

Public patches mean anyone can open the patch for an ad-hoc review. Mailing list members can easily open the patch file in plain text or using a viewer like WinMerge for highlighting.

When the patch is approved, the committer adds it to source control.

Submitting small patches has advantages:

• it’s easier to review a small patch, so you'll get a quality review (Dump a big patch and the reviewer may miss things)
• small patches mean reviews don’t take too long, raising the "code velocity" of the project
• with frequent patches, problems are caught before the developer goes too far in the wrong direction. This is especially important when your team is spread across three continents.

Every day, are you sure?

What if you can’t implement the function or class in a single day? You can't submit a patch unless it’s pristine.

Yes, you can. It's easy using the power of stubs and TODOs.

A stub is a class or function with little or no implementation. For a new class, your first patch will probably be a stub:

class LoginDialog

{
    bool validateUsername()
    {
        // TODO: validate username length, characters, etc.
        return true;
    }
     bool validatePassword()
    {
        // TODO: validate password in database
        return true;
    }

    void doLogin()

    {
        // TODO: 1. pop up a login dialog
        // TODO: 2. get and validate the user credentials
        // TODO: 3. log in to system
    }

    string username;

    string password;

}

Your first patch outlines your class’ design—it compiles, doesn’t hurt the source control, and is small enough for the reviewer to understand easily. Since there are no function implementations so far, the reviewer concentrates on reviewing only the design. Maybe he’ll notice the function to retrieve the database instance is missing, or spot that security risk in storing a plaintext password variable.

The next patches gradually replace the TODOs. You could start by implementing the doLogin() function:

class LoginDialog
{
    bool validateUsername()
    {
        // TODO: validate username length, characters, etc.
        return true;
    }
    
    bool validatePassword()
    {
        // TODO: validate password in database
        return true;
    }
    
    void doLogin()
    {
        LoginDialog dlg = new LoginDialog();
        dlg.ShowModal();
    
        if( validateUsername(dlg.GetUser()) && validatePassword(dlg.GetPwd()) )
        {
            // TODO: login to system
        }
    }
    
    string username;
    string password;
} 

The code reviewer notices a flaw: no error handling if username or password validation fail.

Instead of implementing the error handling, simply add another TODO:

if( validateUsername(dlg.GetUser()) && validatePassword(dlg.GetPwd()) )
{
    // TODO: log in to system
}
else
{
    // TODO: handle log in error
}

The code is functional and error free, though it just brings up a dialog with no functionality. The next patch might implement the password validation. The next could add username validation. Later, you add error handling, etc.

What next?

Patches, stubs and TODOs mean your developers think ahead about what to implement—a good thing. Too often we focus on an algorithm and start implementing full speed ahead without knowing where we’re going.

Working with patches means your team starts self-planning. Like in chess, team members think a few moves ahead, always knowing what their next two patches will be.

TODOs let you prioritize work. If you need a demo by Friday, you’ll rough-in the Login dialog, and leave validation for the next iteration.

Using a consistent keyword, like "TODO," means you can search the code and see what’s left to implement. The TODO count can help a manager estimate how close the project is to completion.

What about once you submit the patch—how do you continue working on the code?

Creating patches as files means one person can work on them and another can review, in parallel. In the above example, I might write a patch for validatePassword(), and another for validateUsername() while waiting for my review. I might even submit patches for another class altogether.

Bottom line: Patch a day encourages good design, and task planning from everyone, not just the project leader. Once team members start planning ahead, each might have 4-5 patches being reviewed on the mailing list at the same time, as the team reaches peak velocity and quality.