by Pete Goodliffe ® San Francisco CODE CRAFT. Copyright © 2007 by Pete Goodliffe. All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage or retrieval system, without the prior written permission of the copyright owner and the publisher. Printed on recycled paper in the United States of America 10 09 08 07 06 1 2 3 4 5 6 7 8 9 ISBN-10: 1-59327-119-0 ISBN-13: 978-1-59327-119-0 Publisher: William Pollock Production Editor: Elizabeth Campbell Cover Design: Octopod Studios Text Illustrations: David Brookes Technical Reviewer: Jon Jagger Copyeditor: Megan Dunchak Compositors: Megan Dunchak, Riley Hoffman, and Christina Samuell Proofreader: Stephanie Provines For information on book distributors or translations, please contact No Starch Press, Inc. directly: No Starch Press, Inc. 555 De Haro Street, Suite 250, San Francisco, CA 94107 phone: 415.863.9900; fax: 415.863.9950; [email protected]; www.nostarch.com Library of Congress Cataloging-in-Publication Data Goodliffe, Pete. Code craft: the practice of writing excellent code / Pete Goodliffe. p. cm. Includes bibliographical references and index. ISBN-13: 978-1-59327-119-0 ISBN-10: 1-59327-119-0 1. Computer programming. 2. Programming languages (Electronic computers) 3. Computer software-- Development. I. Title. QA76.6.G656 2006 005.1--dc22 2006015575 No Starch Press and the No Starch Press logo are registered trademarks of No Starch Press, Inc. Other product and company names mentioned herein may be the trademarks of their respective owners. Rather than use a trademark symbol with every occurrence of a trademarked name, we are using the names only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark. The information in this book is distributed on an “As Is” basis, without warranty. While every precaution has been taken in the preparation of this work, neither the author nor No Starch Press, Inc. shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the information contained in it. All text illustrations copyright © 2006 by David Brookes. To Bryony, my wonderful wife. To Alice, who drew balloons on this book. To Millie, who tasted this book. And to Jessica, who never got a chance to. Psalm 150 B R I E F C O N T E N T S Preface.....................................................................................................................xxvii Acknowledgments......................................................................................................xxxv About the Author.......................................................................................................xxxvii PART I AT THE CODEFACE 1 Chapter 1: On the Defensive Defensive Programming Techniques for Robust Code...........................................................3 Chapter 2: The Best Laid Plans The Layout and Presentation of Source Code....................................................................23 Chapter 3: What’s in a Name? Giving Meaningful Things Meaningful Names..................................................................39 Chapter 4: The Write Stuff Techniques for Writing “Self-Documenting” Code..............................................................57 Chapter 5: A Passing Comment How to Write Code Comments.......................................................................................73 Chapter 6: To Err Is Human Dealing with the Inevitable—Error Conditions in Code.......................................................89 PART II THE SECRET LIFE OF CODE 109 Chapter 7: The Programmer’s Toolbox Using Tools to Construct Software.................................................................................111 Chapter 8: Testing Times The Black Art of Testing Code.......................................................................................129 Chapter 9: Finding Fault Debugging: What to Do When Things Go Wrong..........................................................153 Chapter 10: The Code That Jack Built Mechanisms to Turn Source Code into Executable Code..................................................175 Chapter 11: The Need for Speed Optimizing Programs and Writing Efficient Code............................................................199 Chapter 12: An Insecurity Complex Writing Secure Programs.............................................................................................223 PART III THE SHAPE OF CODE 239 Chapter 13: Grand Designs How to Produce Good Software Designs........................................................................241 Chapter 14: Software Architecture Laying the Foundations of Software Design.....................................................................261 Chapter 15: Software Evolution or Software Revolution? How Does Code Grow?...............................................................................................279 PART IV A HERD OF PROGRAMMERS? 293 Chapter 16: Code Monkeys Fostering the Correct Attitude and Approach to Programming...........................................295 Chapter 17: Together We Stand Teamwork and the Individual Programmer......................................................................315 Chapter 18: Practicing Safe Source Source Control and Self-Control....................................................................................349 PART V PART OF THE PROCESS 365 Chapter 19: Being Specific Writing Software Specifications....................................................................................367 Chapter 20: A Review to a Kill Performing Code Reviews.............................................................................................385 viii Brief Contents Chapter 21: How Long Is a Piece of String? The Black Art of Software Timescale Estimation...............................................................401 PART VI VIEW FROM THE TOP 417 Chapter 22: Recipe for a Program Code Development Methodologies and Processes...........................................................419 Chapter 23: The Outer Limits The Different Programming Disciplines...........................................................................441 Chapter 24: Where Next? All’s Well That Ends Well.............................................................................................459 Answers and Discussion...............................................................................................463 Bibliography...............................................................................................................559 Index.........................................................................................................................565 Brief Contents ix C O N T E N T S I N D E T A I L PREFACE xxvii What’s In It for Me?..............................................................................................xxvii Getting Better......................................................................................................xxviii Who Should Read This Book?..................................................................................xxix What’s Covered?....................................................................................................xxx How This Book Is Organized....................................................................................xxx The Chapters—A Closer Look.................................................................................xxxii Part I: At The Codeface.............................................................................xxxii Part II: The Secret Life of Code...................................................................xxxii Part III: The Shape of Code........................................................................xxxii Part IV: A Herd of Programmers.................................................................xxxii Part V: Part of the Process..........................................................................xxxii Part VI: From the Top................................................................................xxxii How to Use This Book...........................................................................................xxxiii A Note to Mentors..................................................................................xxxiii ACKNOWLEDGMENTS xxxv ABOUT THE AUTHOR xxxvii PART I AT THE CODEFACE 1 ON THE DEFENSIVE Defensive Programming Techniques for Robust Code 3 Toward Good Code..................................................................................................4 Assume the Worst.....................................................................................................4 What Is Defensive Programming?................................................................................6 The Big, Bad World..................................................................................................8 Techniques for Defensive Programming........................................................................8 Employ a Good Coding Style and Sound Design.............................................9 Don’t Code in a Hurry..................................................................................9 Trust No One.............................................................................................10 Write Code for Clarity, Not Brevity..............................................................10 Don’t Let Anyone Tinker with Stuff They Shouldn’t...........................................11 Compile with All Warnings Switched On......................................................11 Use Static Analysis Tools.............................................................................12 Use Safe Data Structures.............................................................................12 Check Every Return Value............................................................................13 Handle Memory (and Other Precious Resources) Carefully..............................13