Summary Clean Code Robert C. Martin Series

Clean Code Robert C. Martin Series The mission of this series is to improve the state of the art of software craftsmanship. The books in this series are technical, pragmatic, and substantial. The authors are highly experienced craftsmen and professionals dedicated to writing about what actually works in practice, as opposed to what might work in theory. You will read about what the author has done, not what he thinks you should do. If the book is about programming, there will be lots of code. If the book is about managing, there will be lots of case studies from real projects. These are the books that all serious practitioners will have on their bookshelves. These are the books that will be remembered for making a difference and for guiding professionals to become true craftsman. Managing Agile Projects Sanjiv Augustine Agile Estimating and Planning Mike Cohn Working Effectively with Legacy Code Michael C. Feathers Agile Java™: Crafting Code with Test-Driven Development Jeff Langr Agile Principles, Patterns, and Practices in C# Robert C. Martin and Micah Martin Agile Software Development: Principles, Patterns, and Practices Robert C. Martin Clean Code: A Handbook of Agile Software Craftsmanship Robert C. Martin UML For Java™ Programmers Robert C. Martin Fit for Developing Software: Framework for Integrated Tests Rick Mugridge and Ward Cunningham Agile Software Development with SCRUM Ken Schwaber and Mike Beedle Extreme Software Engineering: A Hands on Approach Daniel H. Steinberg and Daniel W. Palmer For more information, visit Clean Code A Handbook of Agile Software Craftsmanship The Object Mentors: Robert C. Martin Michael C. Feathers Timothy R. Ottinger Jeffrey J. Langr Brett L. Schuchert James W. Grenning Kevin Dean Wampler Object Mentor Inc. Writing clean code is what you must do in order to call yourself a professional. There is no reasonable excuse for doing anything less than your best. Upper Saddle River, NJ • Boston • Indianapolis • San Francisco New York • Toronto • Montreal • London • Munich • Paris • Madrid Capetown • Sydney • Tokyo • Singapore • Mexico City Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and the publisher was aware of a trademark claim, the designations have been printed with initial capital letters or in all capitals. The authors and publisher have taken care in the preparation of this book, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information or programs contained herein. The publisher offers excellent discounts on this book when ordered in quantity for bulk purchases or special sales, which may include electronic versions and/or custom covers and content particular to your business, training goals, marketing focus, and branding interests. For more information, please contact: U.S. Corporate and Government Sales (800) 382-3419 For sales outside the United States please contact: International Sales Includes bibliographical references and index. ISBN 0-13-235088-2 (pbk. : alk. paper) 1. Agile software development. 2. Computer software—Reliability. I. Title. QA76.76.D47M 005.1—dc22 Copyright © 2009 Pearson Education, Inc. All rights reserved. Printed in the United States of America. This publication is protected by copyright, and permission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise. For information regarding permissions, write to: Pearson Education, Inc Rights and Contracts Department 501 Boylston Street, Suite 900 Boston, MA 02116 Fax: (617) 671-3447 ISBN-13: 978-0-13-235088-4 ISBN-10: 0-13-235088-2 Text printed in the United States on recycled paper at Courier in Stoughton, Massachusetts. First printing July, 2008 For Ann Marie: The ever enduring love of my life. This page intentionally left blank Contents Foreword xix Introduction xxv On the Cover xxix Chapter 1: Clean Code 1 There Will Be Code 2 Bad Code 3 The Total Cost of Owning a Mess 4 The Grand Redesign in the Sky 5 Attitude 5 The Primal Conundrum 6 The Art of Clean Code? 6 What Is Clean Code? 7 Schools of Thought 12 We Are Authors 13 The Boy Scout Rule 14 Prequel and Principles 15 Conclusion 15 Bibliography 15 Chapter 2: Meaningful Names 17 Introduction 17 Use Intention-Revealing Names 18 Avoid Disinformation 19 Make Meaningful Distinctions 20 Use Pronounceable Names 21 Use Searchable Names 22 vii Avoid Encodings 23 Hungarian Notation 23 Member Prefixes 24 Interfaces and Implementations 24 Avoid Mental Mapping 25 Class Names 25 Method Names 25 Don’t Be Cute 26 Pick One Word per Concept 26 Don’t Pun 26 Use Solution Domain Names 27 Use Problem Domain Names 27 Add Meaningful Context 27 Don’t Add Gratuitous Context 29 Final Words 30 Chapter 3: Functions 31 Small! 34 Blocks and Indenting 35 Do One Thing 35 Sections within Functions 36 One Level of Abstraction per Function 36 Reading Code from Top to Bottom: The Stepdown Rule 37 Switch Statements 37 Use Descriptive Names 39 Function Arguments 40 Common Monadic Forms 41 Flag Arguments 41 Dyadic Functions 42 Triads 42 Argument Objects. 43 Argument Lists 43 Verbs and Keywords 43 Have No Side Effects 44 Output Arguments 45 Command Query Separation 45 Prefer Exceptions to Returning Error Codes 46 Extract Try/Catch Blocks 46 Error Handling Is One Thing 47 The E Dependency Magnet 47 Don’t Repeat Yourself 48 Structured Programming 48 How Do You Write Functions Like This? 49 Conclusion 49 SetupTeardownIncluder 50 Bibliography 52 Chapter 4: Comments 53 Comments Do Not Make Up for Bad Code 55 Explain Yourself in Code 55 Good Comments 55 Legal Comments. 55 Informative Comments 56 Explanation of Intent 56 Clarification 57 Warning of Consequences 58 TODO Comments 58 Amplification 59 Javadocs in Public APIs 59 Bad Comments 59 Mumbling 59 Redundant Comments 60 Misleading Comments 63 Mandated Comments 63 Journal Comments 63 Noise Comments 64 Scary Noise 66 Don’t Use a Comment When You Can Use a Function or a Variable. 67 Position Markers 67 Closing Brace Comments 67 Attributions and Bylines 68 Commented-Out Code 68 HTML Comments 69 Nonlocal Information 69 Too Much Information 70 Inobvious Connection 70 Function Headers 70 Javadocs in Nonpublic Code 71 Example 71 Bibliography 74 Chapter 5: Formatting 75 The Purpose of Formatting 76 Vertical Formatting 76 The Newspaper Metaphor 77 Vertical Openness Between Concepts 78 Vertical Density 79 Vertical Distance 80 Vertical Ordering 84 Horizontal Formatting 85 Horizontal Openness and Density 86 Horizontal Alignment 87 Indentation 88 Dummy Scopes 90 Team Rules 90 Uncle Bob’s Formatting Rules 90 Chapter 6: Objects and Data Structures 93 Data Abstraction 93 Data/Object Anti-Symmetry 95 The Law of Demeter 97 Train Wrecks 98 Hybrids 99 Hiding Structure 99 Data Transfer Objects 100 Active Record 101 Conclusion 101 Bibliography 101 Chapter 7: Error Handling 103 Use Exceptions Rather Than Return Codes 104 Write Your Try-Catch-Finally Statement First 105 Use Unchecked Exceptions 106 Provide Context with Exceptions 107 Define Exception Classes in Terms of a Caller’s Needs 107 Define the Normal Flow 109 Don’t Return Null 110 Don’t Pass Null 111 Conclusion 112 Bibliography 112 Chapter 8: Boundaries 113 Using Third-Party Code 114 Exploring and Learning Boundaries 116 Learning log4j 116 Learning Tests Are Better Than Free 118 Using Code That Does Not Yet Exist 118 Clean Boundaries 120 Bibliography 120 Chapter 9: Unit Tests 121 The Three Laws of TDD 122 Keeping Tests Clean 123 Tests Enable the -ilities 124 Clean Tests 124 Domain-Specific Testing Language 127 A Dual Standard 127 One Assert per Test 130 Single Concept per Test 131 F.I.R.S.T 132 Conclusion 133 Bibliography 133 Chapter 10: Classes 135 Class Organization 136 Encapsulation 136 Classes Should Be Small! 136 The Single Responsibility Principle 138 Cohesion 140 Maintaining Cohesion Results in Many Small Classes 141 Organizing for Change 147 Isolating from Change 149 Bibliography 151 Chapter 11: Systems 153 How Would You Build a City? 154 Separate Constructing a System from Using It 154 Separation of Main 155 Factories 155 Dependency Injection 157 Scaling Up 157 Cross-Cutting Concerns 160 Java Proxies 161 Pure Java AOP Frameworks 163 AspectJ Aspects 166 Test Drive the System Architecture 166 Optimize Decision Making 167 Use Standards Wisely, When They Add Demonstrable Value 168 Systems Need Domain-Specific Languages 168 Conclusion 169 Bibliography 169 Chapter 12: Emergence 171 Getting Clean via Emergent Design 171 Simple Design Rule 1: Runs All the Tests 172 Simple Design Rules 2–4: Refactoring 172 No Duplication 173 Expressive 175 Minimal Classes and Methods 176 Conclusion 176 Bibliography 176 Chapter 13: Concurrency 177 Why Concurrency? 178 Myths and Misconceptions 179 Challenges 180 Concurrency Defense Principles 180 Single Responsibility Principle 181 Corollary: Limit the Scope of Data 181 Corollary: Use Copies of Data 181 Corollary: Threads Should Be as Independent as Possible 182 Know Your Library 182 Thread-Safe Collections 182 Know Your Execution Models 183 Producer-Consumer 184 Readers-Writers 184 Dining Philosophers 184 Beware Dependencies Between Synchronized Methods 185 Keep Synchronized Sections Small 185 Writing Correct Shut-Down Code Is Hard 186 Testing Threaded Code 186 Treat Spurious Failures as Candidate Threading Issues 187 Get Your Nonthreaded Code Working First 187 Make Your Threaded Code Pluggable 187 Make Your Threaded Code Tunable 187 Run with More Threads Than Processors 188 Run on Different Platforms 188 Instrument Your Code to Try and Force Failures 188 Hand-Coded 189 Automated 189 Conclusion 190 Bibliography 191 Chapter 14: Successive Refinement 193 Args Implementation 194 How Did I Do This? 200 Args: The Rough Draft 201 So I Stopped 212 On Incrementalism 212 String Arguments 214 Conclusion 250 Chapter 15: JUnit Internals 251 The JUnit Framework 252 Conclusion 265 Chapter 16: Refactoring SerialDate 267 First, Make It Work 268 Then Make It Right 270 Conclusion 284 Bibliography 284 Chapter 17: Smells and Heuristics 285 Comments 286 C1: Inappropriate Information 286 C2: Obsolete Comment 286 C3: Redundant Comment 286 C4: Poorly Written Comment 287 C5: Commented-Out Code 287 Environment 287 E1: Build Requires More Than One Step 287 E2: Tests Require More Than One Step 287 Functions 288 F1: Too Many Arguments 288 F2: Output Arguments 288 F3: Flag Arguments 288 F4: Dead Function 288 General 288 G1: Multiple Languages in One Source File 288 G2: Obvious Behavior Is Unimplemented 288 G3: Incorrect Behavior at the Boundaries 289 G4: Overridden Safeties 289 G5: Duplication 289 G6: Code at Wrong Level of Abstraction 290 G7: Base Classes Depending on Their Derivatives 291 G8: Too Much Information 291 G9: Dead Code 292 G10: Vertical Separation 292 G11: Inconsistency 292 G12: Clutter 293 G13: Artificial Coupling 293 G14: Feature Envy 293 G15: Selector Arguments 294 G16: Obscured Intent 295 G17: Misplaced Responsibility 295 G18: Inappropriate Static 296 G19: Use Explanatory Variables 296 G20: Function Names Should Say What They Do 297 G21: Understand the Algorithm 297 G22: Make Logical Dependencies Physical 298 G23: Prefer Polymorphism to If/Else or Switch/Case 299 G24: Follow Standard Conventions 299 G25: Replace Magic Numbers with Named Constants 300 G26: Be Precise 301 G27: Structure over Convention 301 G28: Encapsulate Conditionals 301 G29: Avoid Negative Conditionals 302 G30: Functions Should Do One Thing 302 G31: Hidden Temporal Couplings 302 G32: Don’t Be Arbitrary 303 G33: Encapsulate Boundary Conditions 304 G34: Functions Should Descend Only One Level of Abstraction 304 G35: Keep Configurable Data at High Levels 306 G36: Avoid Transitive Navigation 306 Java 307 J1: Avoid Long Import Lists by Using Wildcards 307 J2: Don’t Inherit Constants 307 J3: Constants versus Enums 308 Names 309 N1: Choose Descriptive Names 309 N2: Choose Names at the Appropriate Level of Abstraction 311 N3: Use Standard Nomenclature Where Possible 311 N4: Unambiguous Names 312 N5: Use Long Names for Long Scopes 312 N6: Avoid Encodings 312 N7: Names Should Describe Side-Effects. 313 Tests 313 T1: Insufficient Tests 313 T2: Use a Coverage Tool! 313 T3: Don’t Skip Trivial Tests 313 T4: An Ignored Test Is a Question about an Ambiguity 313 T5: Test Boundary Conditions 314 T6: Exhaustively Test Near Bugs 314 T7: Patterns of Failure Are Revealing 314 T8: Test Coverage Patterns Can Be Revealing 314 T9: Tests Should Be Fast 314 Conclusion 314 Bibliography 315 Appendix A: Concurrency II 317 Client/Server Example 317 The Server 317 Adding Threading 319 Server Observations 319 Conclusion 321 Possible Paths of Execution 321 Number of Paths 322 Digging Deeper 323 Conclusion 326 Knowing Your Library 326 Executor Framework 326 Nonblocking Solutions 327 Nonthread-Safe Classes 328 Dependencies Between Methods Can Break Concurrent Code 329 Tolerate the Failure 330 Client-Based Locking 330 Server-Based Locking 332 Increasing Throughput 333 Single-Thread Calculation of Throughput 334 Multithread Calculation of Throughput 335 Deadlock 335 Mutual Exclusion 336 Lock & Wait 337 No Preemption 337 Circular Wait 337 Breaking Mutual Exclusion 337 Breaking Lock & Wait 338 Breaking Preemption 338 Breaking Circular Wait 338 Testing Multithreaded Code 339 Tool Support for Testing Thread-Based Code 342 Conclusion 342 Tutorial: Full Code Examples 343 Client/Server Nonthreaded 343 Client/Server Using Threads 346 Appendix B: .SerialDate 349 Appendix C: Cross References of Heuristics 409 Epilogue 411 Index 413 This page intentionally left blank Foreword One of our favorite candies here in Denmark is Ga-Jol, whose strong licorice vapors are a perfect complement to our damp and often chilly weather. Part of the charm of Ga-Jol to us Danes is the wise or witty sayings printed on the flap of every box top. I bought a two- pack of the delicacy this morning and found that it bore this old Danish saw: Ærlighed i små ting er ikke nogen lille ting. “Honesty in small things is not a small thing.” It was a good omen consistent with what I already wanted to say here. Small things matter. This is a book about humble concerns whose value is nonetheless far from small. God is in the details, said the architect Ludwig mies van der Rohe. This quote recalls contemporary arguments about the role of architecture in software development, and par- ticularly in the Agile world. Bob and I occasionally find ourselves passionately engaged in this dialogue. And yes, mies van der Rohe was attentive to utility and to the timeless forms of building that underlie great architecture. On the other hand, he also personally selected every doorknob for every house he designed. Why? Because small things matter. In our ongoing “debate” on TDD, Bob and I have discovered that we agree that soft- ware architecture has an important place in development, though we likely have different visions of exactly what that means. Such quibbles are relatively unimportant, however, because we can accept for granted that responsible professionals give some time to think- ing and planning at the outset of a project. The late-1990s notions of design driven only by the tests and the code are long gone. Yet attentiveness to detail is an even more critical foundation of professionalism than is any grand vision. First, it is through practice in the small that professionals gain proficiency and trust for practice in the large. Second, the smallest bit of sloppy construction, of the door that does not close tightly or the slightly crooked tile on the floor, or even the messy desk, completely dispels the charm of the larger whole. That is what clean code is about. Still, architecture is just one metaphor for software development, and in particular for that part of software that delivers the initial product in the same sense that an architect delivers a pristine building. In these days of Scrum and Agile, the focus is on quickly bringing product to market. We want the factory running at top speed to produce software. These are human factories: thinking, feeling coders who are working from a product back- log or user story to create product. The manufacturing metaphor looms ever strong in such thinking. The production aspects of Japanese auto manufacturing, of an assembly-line world, inspire much of Scrum. xix Yet even in the auto industry, the bulk of the work lies not in manufacturing but in maintenance—or its avoidance. In software, 80% or more of what we do is quaintly called “maintenance”: the act of repair. Rather than embracing the typical Western focus on pro- ducing good software, we should be thinking more like home repairmen in the building industry, or auto mechanics in the automotive field. What does Japanese management have to say about that? In about 1951, a quality approach called Total Productive Maintenance (TPM) came on the Japanese scene. Its focus is on maintenance rather than on production. One of the major pillars of TPM is the set of so-called 5S principles. 5S is a set of disciplines—and here I use the term “discipline” instructively. These 5S principles are in fact at the founda- tions of Lean—another buzzword on the Western scene, and an increasingly prominent buzzword in software circles. These principles are not an option. As Uncle Bob relates in his front matter, good software practice requires such discipline: focus, presence of mind, and thinking. It is not always just about doing, about pushing the factory equipment to pro- duce at the optimal velocity. The 5S philosophy comprises these concepts: • Seiri, or organization (think “sort” in English). Knowing where things are—using approaches such as suitable naming—is crucial. You think naming identifiers isn’t important? Read on in the following chapters. • Seiton, or tidiness (think “systematize” in English). There is an old American saying: A place for everything, and everything in its place. A piece of code should be where you expect to find it—and, if not, you should re-factor to get it there. • Seiso, or cleaning (think “shine” in English): Keep the workplace free of hanging wires, grease, scraps, and waste. What do the authors here say about littering your code with comments and commented-out code lines that capture history or wishes for the future? Get rid of them. • Seiketsu, or standardization: The group agrees about how to keep the workplace clean. Do you think this book says anything about having a consistent coding style and set of practices within the group? Where do those standards come from? Read on. • Shutsuke, or discipline (self-discipline). This means having the discipline to follow the practices and to frequently reflect on one’s work and be willing to change. If you take up the challenge—yes, the challenge—of reading and applying this book, you’ll come to understand and appreciate the last point. Here, we are finally driving to the roots of responsible professionalism in a profession that should be concerned with the life cycle of a product. As we maintain automobiles and other machines under TPM, break- down maintenance—waiting for bugs to surface—is the exception. Instead, we go up a level: inspect the machines every day and fix wearing parts before they break, or do the equivalent of the proverbial 10,000-mile oil change to forestall wear and tear. In code, refactor mercilessly. You can improve yet one level further, as the TPM movement inno- vated over 50 years ago: build machines that are more maintainable in the first place. Mak- ing your code readable is as important as making it executable. The ultimate practice, introduced in TPM circles around 1960, is to focus on introducing entire new machines or replacing old ones. As Fred Brooks admonishes us, we should probably re-do major soft- ware chunks from scratch every seven years or so to sweep away creeping cruft. Perhaps we should update Brooks’ time constant to an order of weeks, days or hours instead of years. That’s where detail lies. There is great power in detail, yet there is something humble and profound about this approach to life, as we might stereotypically expect from any approach that claims Japa- nese roots. But this is not only an Eastern outlook on life; English and American folk wis- dom are full of such admonishments. The Seiton quote from above flowed from the pen of an Ohio minister who literally viewed neatness “as a remedy for every degree of evil.” How about Seiso? Cleanliness is next to godliness. As beautiful as a house is, a messy desk robs it of its splendor. How about Shutsuke in these small matters? He who is faithful in little is faithful in much. How about being eager to re-factor at the responsible time, strengthening one’s position for subsequent “big” decisions, rather than putting it off? A stitch in time saves nine. The early bird catches the worm. Don’t put off until tomorrow what you can do today. (Such was the original sense of the phrase “the last responsible moment” in Lean until it fell into the hands of software consultants.) How about calibrat- ing the place of small, individual efforts in a grand whole? Mighty oaks from little acorns grow. Or how about integrating simple preventive work into everyday life? An ounce of prevention is worth a pound of cure. An apple a day keeps the doctor away. Clean code honors the deep roots of wisdom beneath our broader culture, or our culture as it once was, or should be, and can be with attentiveness to detail. Even in the grand architectural literature we find saws that hark back to these sup- posed details. Think of mies van der Rohe’s doorknobs. That’s seiri. That’s being attentive to every variable name. You should name a variable using the same care with which you name a first-born child. As every homeowner knows, such care and ongoing refinement never come to an end. The architect Christopher Alexander—father of patterns and pattern languages—views every act of design itself as a small, local act of repair. And he views the craftsmanship of fine structure to be the sole purview of the architect; the larger forms can be left to patterns and their application by the inhabitants. Design is ever ongoing not only as we add a new room to a house, but as we are attentive to repainting, replacing worn carpets, or upgrad- ing the kitchen sink. Most arts echo analogous sentiments. In our search for others who ascribe God’s home as being in the details, we find ourselves in the good company of the 19th century French author Gustav Flaubert. The French poet Paul Valery advises us that a poem is never done and bears continual rework, and to stop working on it is abandonment. Such preoccupation with detail is common to all endeavors of excellence. So maybe there is little new here, but in reading this book you will be challenged to take up good disci- plines that you long ago surrendered to apathy or a desire for spontaneity and just “responding to change.” Unfortunately, we usually don’t view such concerns as key cornerstones of the art of programming. We abandon our code early, not because it is done, but because our value system focuses more on outward appearance than on the substance of what we