What Readers Are Saying About Debug It! Paul does an excellent job of explaining the technical, intellectual, and psychological aspects of all phases of debugging: preventing bugs in the first place, diagnosing and fixing bugs, and making sure that the same bugs don’t happen again. Applying any or all of the ideas from this book will improve the overall quality of your software projects. Sure, the technical issues are well covered but how Paul also explains the psychological angles is what makes this book exceptional. Frederic Daoud Author, Stripes...and Java Web Development Is Fun Again I wholeheartedly recommend this book to software engineers generally but more specifically to team leads who need to know how to set up their teams for best practice. Allan McLeod Founder and CTO, Isaacc Software Debug It! does a great job of setting the scene for debugging and get- ting you into the right mind-set while also talking about the complica- tions that can arise once the bug is found and squashed. It’s worth a look for the anecdotes alone, to see the lengths that people go to when trying to understand truly bizarre defects. Jon Dickinson Author, Grails 1.1 Web Application Development Debugging has been a folk art for so long that it’s great to have some- one put all the tried-and-true techniques together. Debug It! is the perfect book to pull out when you’re disillusioned with the brain- breaking process of creating good software. With this tool chest of assertions, logging, refactoring, and other good stuff, you’ll feel like you’re Sherlock Holmes and solving the case is inevitable. Craig Riecke Author, Mastering Dojo: JavaScript and Ajax Tools for Great Web Experiences This book is like a companion volume to The Pragmatic Programmer, applying the same focus on craftsmanship to the debugging process. Ian Dees Author, Scripted GUI Testing with Ruby Paul Butcher has brought long overdue attention to the methods of debugging, a fundamental activity for every software developer yet one that remains an exercise of intuition and guesswork for most in the profession. Paul’s gentle writing style belies the discipline in his tech- nique. Before you know it, you’ll be an engineer instead of a hacker. Bill Karwin Software Engineer, Karwin Software Solutions, LLC Debug It! Find, Repair, and Prevent Bugs in Your Code Paul Butcher The Pragmatic Bookshelf Raleigh, North Carolina Dallas, Texas Many of the designations used by manufacturers and sellers to distinguish their prod- ucts are claimed as trademarks. Where those designations appear in this book, and The Pragmatic Programmers, LLC was aware of a trademark claim, the designations have been printed in initial capital letters or in all capitals. The Pragmatic Starter Kit, The Pragmatic Programmer, Pragmatic Programming, Pragmatic Bookshelf and the linking g device are trademarks of The Pragmatic Programmers, LLC. Every precaution was taken in the preparation of this book. However, the publisher assumes no responsibility for errors or omissions, or for damages that may result from the use of information (including program listings) contained herein. Our Pragmatic courses, workshops, and other products can help you and your team create better software and have more fun. For more information, as well as the latest Pragmatic titles, please visit us at http://www.pragprog.com Copyright © 2009 Paul Butcher. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmit- ted, in any form, or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior consent of the publisher. Printed in the United States of America. ISBN-10: 1-934356-28-X ISBN-13: 978-1-934356-28-9 Printed on acid-free paper. P1.0 printing, November 2009 Version: 2009-11-4 Contents Preface 10 About This Book .......................... 10 Acknowledgments .......................... 11 I The Heart of the Problem 13 1 A Method in the Madness 14 1.1 Debugging Is More Than “Making the Bug Go Away” . 14 1.2 The Empirical Approach .................. 16 1.3 The Core Debugging Process ............... 17 1.4 First Things First ...................... 18 1.5 Put It in Action ....................... 22 2 Reproduce 23 2.1 Reproduce First, Ask Questions Later .......... 23 2.2 Controlling the Software .................. 25 2.3 Controlling the Environment ............... 26 2.4 Controlling Inputs ..................... 28 2.5 Refining Your Reproduction ................ 36 2.6 What If You Really Can’t Reproduce It? ......... 45 2.7 Put It in Action ....................... 48 3 Diagnose 49 3.1 Stand Back—I’m Going to Try Science .......... 49 3.2 Stratagems .......................... 56 3.3 Debuggers .......................... 62 3.4 Pitfalls ............................ 63 3.5 Mind Games ......................... 67 3.6 Validate Your Diagnosis .................. 72 3.7 Put It in Action ....................... 73 CONTENTS 8 4 Fix 74 4.1 Clearing the Decks ..................... 75 4.2 Testing ............................ 76 4.3 Fix the Cause, Not the Symptoms ............ 78 4.4 Refactoring .......................... 80 4.5 Checking In ......................... 82 4.6 Get Your Code Reviewed .................. 83 4.7 Put It in Action ....................... 84 5 Reflect 85 5.1 How Did It Ever Work? ................... 85 5.2 What Went Wrong? ..................... 86 5.3 It’ll Never Happen Again .................. 89 5.4 Close the Loop ........................ 92 5.5 Put It in Action ....................... 93 II The Bigger Picture 94 6 Discovering That You Have a Problem 95 6.1 Tracking Bugs ........................ 95 6.2 Working with Users ..................... 100 6.3 Working with Support Staff ................ 105 6.4 Put It in Action ....................... 107 7 Pragmatic Zero Tolerance 108 7.1 Bugs Take Priority ..................... 108 7.2 The Debugging Mind-Set .................. 111 7.3 Digging Yourself Out of a Quality Hole .......... 113 7.4 Put It in Action ....................... 118 III Debug-Fu 119 8 Special Cases 120 8.1 Patching Existing Releases ................ 120 8.2 Backward Compatibility .................. 121 8.3 Concurrency ......................... 126 8.4 Heisenbugs ......................... 128 8.5 Performance Bugs ..................... 130 8.6 Embedded Software ..................... 132 8.7 Bugs in Third-Party Software ............... 135 8.8 Put It in Action ....................... 140 CONTENTS 9 9 The Ideal Debugging Environment 141 9.1 Automated Testing ..................... 141 9.2 Source Control ....................... 144 9.3 Automatic Builds ...................... 149 9.4 Put It in Action ....................... 157 10 Teach Your Software to Debug Itself 158 10.1 Assumptions and Assertions ............... 158 10.2 Debugging Builds ...................... 168 10.3 Resource Leaks and Exception Handling ........ 173 10.4 Put It in Action ....................... 180 11 Anti-patterns 181 11.1 Priority Inflation ....................... 181 11.2 Prima Donna ......................... 182 11.3 Maintenance Team ..................... 184 11.4 Firefighting .......................... 186 11.5 Rewrite ............................ 187 11.6 No Code Ownership ..................... 189 11.7 Black Magic ......................... 189 11.8 Put It in Action ....................... 190 A Resources 192 A.1 Source Control and Issue-Tracking Systems . 192 A.2 Build and Continuous Integration Tools ......... 195 A.3 Useful Libraries ....................... 197 A.4 Other Tools ......................... 199 B Bibliography 203 Index 205 Preface I’ve always been mystified why so few books are available on debugging. You can buy any number on every other aspect of software engineering such as design, code construction, requirements capture, methodolo- gies...the list is endless. And yet, for some reason, debugging has been almost (not quite but very nearly) ignored by authors and publishers. I hope that this book can help remedy the situation. If you write code, it’s a certainty that at some point (possibly very soon afterward) you’re going to have to debug it. Debugging is, more than anything else, an intellectual process—it doesn’t take place within a debugger or your code but inside your mind. Reaching an understand- ing of the root cause of the problem is the cornerstone upon which everything else depends. Over the years, I’ve been fortunate to work with a number of incredi- bly talented teams on a wide range of software. I’ve worked at all levels of abstraction from microcode on bit-slice processors through device drivers, embedded code, mainstream desktop software, and web appli- cations. I hope that I can pass along some of the lessons I’ve learned from my colleagues along the way. About This Book This book is divided into three parts, each of which considers a partic- ular aspect of debugging: “The Heart of the Problem”: This part introduces the empirical approach, which leverages our software’s unique ability to show us what’s going on, and the core debugging method (reproduce, diagnose, fix, reflect) that relies upon it. ACKNOWLEDGMENTS 11 “The Bigger Picture”: How do we find out that there’s a problem that needs fixing in the first place? And how does debugging integrate into the wider software development process? “Debug-Fu”: In the third and final part, we’ll turn our attention to a number of advanced topics: • Although the approaches discussed earlier in the book apply to all bugs, certain types of bugs benefit from special treat- ment. • Debugging starts long