Outside the Institute of Advanced Theoretical Physics

Critical Bug Fix Checklist

When I have to address a critical bug, I try to approach it warily. Even more, I try to approach it like the bug is a plane and I'm about to fly it across the country.

To do that, one of the tools I use is a checklist, that I force myself to walk through. I've found that a bug fix checklist has lowered the number of returned defects by 60%. That's a major increase in productivity.

This is my checklist below for fixing a critical bug, and deploying a patch to the production server.

Critical Bug Fix Checklist

Pre-Fix

• I have identified the branch to which this patch must be applied
• I was able to duplicate the bug in the original environment
• I have duplicated the bug on my local dev environment
• I was able to track the workflow through my debugger to the source of the problem
• I have described the bug fix to a second person, who concurs with my conclusion

Fix

• Code comments were added appropriately, explaining the fix
• The bug ticket/tracking number referenced in the code comments
• I reviewed the  SVN diffs on changed code
• A second developer has looked at the SVN diffs
• I have shown the fix to the person who reported the issue

Unit tests & QA

• I have written unit tests
• All new unit tests pass
• My changes did not break any existing unit tests
• If no unit tests were written, and unit tests can be written, a ticket has been filed as technical debt, to complete the tests, and the ticket is linked to the ticket I am working on now
• I have manually tested the fix and got the expected results
• I have tested on IE
• I have verified that no javascript errors 
• I have described a test case on the bug ticket, expected results, and areas of impact

Documentation & Bug Ticket

• A description of the bug cause was added
• I have documented on the ticket the possible areas affected
• I have identified the root cause
• I have indicated how this situation could be avoided in the future

Before  Deployment  Checklist

• I have verified the fix is in the correct branch
• I have rebuilt this branch on the testing server
• The fix has been verified on the testing server
• I have verified that there is no currently non-releasable patch in this branch that cannot yet be uploaded

Post Deployment Checklist

• I have verified which sites and servers are to receive the upload
• A dry run has occurred
• I have uploaded to a single site/server to verify
• I have uploaded to all servers
• I have verified the fix on the original site on which the issue was reported
• An email has been sent to the relevant parties or representatives, indicating that the issue has been resolved, taken live. The email also identifies the area of concern and what users should now expect to see. 

What does " Uncaught exception 'PDOException' with message 'You cannot serialize or unserialize PDO instances'" mean?

If you are running unit tests in PHP, you may get the following hair-pulling error:

Uncaught exception 'PDOException' with message  
    'You cannot serialize or unserialize PDO instances'

It means that something with a doctrine/pdo went wrong in one of your tests. Since serialize does not work on pdo-classes, it prints out this message. If you want doctrines/PDOs message, run only the one test with process isolation turned off and you will get the error-message.

Software development in a nutshell

Programming today is a race between software engineers striving to build bigger and better idiot-proof programs, and the Universe trying to produce bigger and better idiots. So far, the Universe is winning. -  Rich Cook

Second principle of code review: write an ode to the code

<< Previous Article: 'The First Principle of Code Review: Check Yourself at the Door'

Stop me if you heard this one. You have written a hundred lines of code. You pass it off to a code reviewer. He tears it to ribbons.

He tells you to restructure some conditionals. He tells you that an algorithm would be better written another way. He tells you to use different classes than the ones you are using.

Then you ask him if he knows what the code does. And he doesn't.

As autistic coders, we are rarely so bold as to challenge the reviewer about his knowledge of what our code does, and we rarely ask this simple question.

But we should.

And, when you are reviewing someone else's code, you should be asking the same thing to yourself: 'What is the purpose of this code?'

Above all else, a code review should be used to determine if you have written understandable code. Given the comments, given the structure of the code, given the flow of control, are you able to say back to the coder what his code does?

If you can't, then one of two things is true:

1. The code fails the review
2. The code reviewer fails the review

 In either case, however, the code review should come to a full stop. There is no point in critiquing code whose purpose you don't understand.

There is no point in giving pointers when you don't know the point of the code.

Make sure you can briefly describe the purpose of the code. If you don't understand what it is supposed to do, how do you know it's does what it's supposed to do?

If you don't understand why it is structured the way it is structured, how do you know if your structural suggestions are correct?

The best code comments I have seen

/**
 *  This probably returns the id
 **/
// probably??
function getRecordId(){

This code comment was written by John. Every company has a John. He's the master programmer who wreaked havoc years ago at the company. There is no module that doesn't have the finger of John in it. And, years after he has gone, there is no problem in the code that isn't blamed on John.

// Autogenerated, do not edit. All changes will be undone.

John added this to a particularly long and complicated method. This would have been sufficient to deter code meddlers, but he also added a comment at the end of the method:

// I find that if you want to keep someone from messing 
// with your code, add a comment that it's auto generated.

This is my all time favorite:

// 07/12/08 - Temporary logging for debug purposes
// 01/11-10 - temporary????

And, of course, there was a lot of this:

catch (Exception $e){
  // annnnd throw it down a hole
}