Chapter 1. Clean Code Page 1 There Will Be Code Page 2 Bad Code Page 3 The Total Cost of Owning a Mess Page 4 The Grand Redesign in the Sky Page 5 Attitude Page 5 The Primal Conundrum Page 6 The Art of Clean Code? Page 6 What Is Clean Code? Page 7 Schools of Thought Page 12 We Are Authors Page 13 The Boy Scout Rule Page 14 Prequel and Principles Page 15 Conclusion Page 15 Bibliography Page 15 Chapter 2. Meaningful Names Page 17 A Introduction Page 17 Use Intention-Revealing Names Page 18 Avoid Disinformation Page 19 Make Meaningful Distinctions Page 20 Use Pronounceable Names Page 21 Use Searchable Names Page 22 Avoid Encodings Page 23 Hungarian Notation Page 23 Member Prefixes Page 24 Interfaces and Implementations Page 24 Avoid Mental Mapping Page 25 Class Names Page 25 Method Names Page 25 Don't Be Cute Page 26 Pick One Word per Concept Page 26 Don't Pun Page 26 Use Solution Domain Names Page 27 Use Problem Domain Names Page 27 Add Meaningful Context Page 27 Don't Add Gratuitous Context Page 29 Final Words Page 30 Chapter 3. Functions Page 31 Small! Page 34 Blocks and Indenting Page 35 Do One Thing Page 35 Sections within Functions Page 36 One Level of Abstraction per Function Page 36 Reading Code from Top to Bottom: The Stepdown Rule Page 37 Switch Statements Page 37 Use Descriptive Names Page 39 Function Arguments Page 40 Common Monadic Forms Page 41 Flag Arguments Page 41 Dyadic Functions Page 42 Triads Page 42 Argument Objects Page 43 Argument Lists Page 43 Verbs and Keywords Page 43 Have No Side Effects Page 44 Output Arguments Page 45 Command Query Separation Page 45 Prefer Exceptions to Returning Error Codes Page 46 Extract Try/Catch Blocks Page 46 Error Handling Is One Thing Page 47 The Error.java Dependency Magnet Page 47 Don't Repeat Yourself Page 48 Structured Programming Page 48 How Do You Write Functions Like This? Page 49 Conclusion Page 49 SetupTeardownIncluder Page 50 Bibliography Page 52 Chapter 4. Comments Page 53 Comments Do Not Make Up for Bad Code Page 55 Explain Yourself in Code Page 55 Good Comments Page 55 Legal Comments Page 55 Informative Comments Page 56 Explanation of Intent Page 56 Clarification Page 57 Warning of Consequences Page 58 TODO Comments Page 58 Amplification Page 59 Javadocs in Public APIs Page 59 Bad Comments Page 59 Mumbling Page 59 Redundant Comments Page 60 Misleading Comments Page 63 Mandated Comments Page 63 Journal Comments Page 63 Noise Comments Page 64 Scary Noise Page 66 Don't Use a Comment When You Can Use a Function or a Variable Page 67 Position Markers Page 67 Closing Brace Comments Page 67 Attributions and Bylines Page 68 Commented-Out Code Page 68 HTML Comments Page 69 Nonlocal Information Page 69 Too Much Information Page 70 Inobvious Connection Page 70 Function Headers Page 70 Javadocs in Nonpublic Code Page 71 Example Page 71 Bibliography Page 74 Chapter 5. Formatting Page 75 The Purpose of Formatting Page 76 Vertical Formatting Page 76 The Newspaper Metaphor Page 77 Vertical Openness Between Concepts Page 78 Vertical Density Page 79 Vertical Distance Page 80 Vertical Ordering Page 84 Horizontal Formatting Page 85 Horizontal Openness and Density Page 86 Horizontal Alignment Page 87 Indentation Page 88 Dummy Scopes Page 90 Team Rules Page 90 Uncle Bob's Formatting Rules Page 90 Chapter 6. Objects and Data Structures Page 93 Data Abstraction Page 93 Data/Object Anti-Symmetry Page 95 The Law of Demeter Page 97 Train Wrecks Page 98 Hybrids Page 99 Hiding Structure Page 99 Data Transfer Objects Page 100 Active Record Page 101 Conclusion Page 101 Bibliography Page 101 Chapter 7. Error Handling Page 103 Use Exceptions Rather Than Return Codes Page 104 Write Your Try-Catch-Finally Statement First Page 105 Use Unchecked Exceptions Page 106 Provide Context with Exceptions Page 107 Define Exception Classes in Terms of a Caller's Needs Page 107 Define the Normal Flow Page 109 Don't Return Null Page 110 Don't Pass Null Page 111 Conclusion Page 112 Bibliography Page 112 Chapter 8. Boundaries Page 113 Using Third-Party Code Page 114 Exploring and Learning Boundaries Page 116 Learning log4j Page 116 Learning Tests Are Better Than Free Page 118 Using Code That Does Not Yet Exist Page 118 Clean Boundaries Page 120 Bibliography Page 120 Chapter 9. Unit Tests Page 121 The Three Laws of TDD Page 122 Keeping Tests Clean Page 123 Tests Enable the -ilities Page 124 Clean Tests Page 124 Domain-Specific Testing Language Page 127 A Dual Standard Page 127 One Assert per Test Page 130 Single Concept per Test Page 131 F.I.R.S.T. Page 132 Conclusion Page 133 Bibliography Page 133 Chapter 10. Classes Page 135 Class Organization Page 136 Encapsulation Page 136 Classes Should Be Small! Page 138 The Single Responsibility Principle Page 138 Cohesion Page 140 Maintaining Cohesion Results in Many Small Classes Page 141 Organizing for Change Page 147 Isolating from Change Page 149 Bibliography Page 151 Chapter 11. Systems Page 153 How Would You Build a City? Page 154 Separate Constructing a System from Using It Page 154 Separation of Main Page 155 Factories Page 155 Dependency Injection Page 157 Scaling Up Page 157 Cross-Cutting Concerns Page 160 Java Proxies Page 161 Pure Java AOP Frameworks Page 163 AspectJ Aspects Page 166 Test Drive the System Architecture Page 166 Optimize Decision Making Page 167 Use Standards Wisely, When They Add Demonstrable Value Page 168 Systems Need Domain-Specific Languages Page 168 Conclusion Page 169 Bibliography Page 169 Chapter 12. Emergence Page 171 Getting Clean via Emergent Design Page 171 Simple Design Rule 1: Runs All the Tests Page 172 Simple Design Rules 2-4: Refactoring Page 172 No Duplication Page 173 Expressive Page 175 Minimal Classes and Methods Page 176 Conclusion Page 176 Bibliography Page 176 Chapter 13. Concurrency Page 177 Why Concurrency? Page 178 Myths and Misconceptions Page 179 Challenges Page 180 Concurrency Defense Principles Page 180 Single Responsibility Principle Page 181 Corollary: Limit the Scope of Data Page 181 Corollary: Use Copies of Data Page 181 Corollary: Threads Should Be as Independent as Possible Page 182 Know Your Library Page 182 Thread-Safe Collections Page 182 Know Your Execution Models Page 183 Producer-Consumer Page 184 Readers-Writers Page 184 Dining Philosophers Page 184 Beware Dependencies Between Synchronized Methods Page 185 Keep Synchronized Sections Small Page 185 Writing Correct Shut-Down Code Is Hard Page 186 Testing Threaded Code Page 186 Treat Spurious Failures as Candidate Threading Issues Page 187 Get Your Nonthreaded Code Working First Page 187 Make Your Threaded Code Pluggable Page 187 Make Your Threaded Code Tunable Page 187 Run with More Threads Than Processors Page 188 Run on Different Platforms Page 188 Instrument Your Code to Try and Force Failures Page 188 Hand-Coded Page 189 Automated Page 189 Conclusion Page 190 Bibliography Page 191 Chapter 14. Successive Refinement Page 193 Args Implementation Page 194 How Did I Do This? Page 200 Args: The Rough Draft Page 201 So I Stopped Page 212 On Incrementalism Page 212 String Arguments Page 214 Conclusion Page 250 Chapter 15. JUnit Internals Page 251 The JUnit Framework Page 252 Conclusion Page 265 Chapter 16. Refactoring SerialDate Page 267 First, Make It Work Page 268 Then Make It Right Page 270 Conclusion Page 284 Bibliography Page 284 Chapter 17. Smells and Heuristics Page 285 Comments Page 286 C1. Inappropriate Information Page 286 C2. Obsolete Comment Page 286 C3. Redundant Comment Page 286 C4. Poorly Written Comment Page 287 C5. Commented-Out Code Page 287 Environment Page 287 E1. Build Requires More Than One Step Page 287 E2. Tests Require More Than One Step Page 287 Functions Page 288 F1. Too Many Arguments Page 288 F2. Output Arguments Page 288 F3. Flag Arguments Page 288 F4. Dead Function Page 288 General Page 288 G1. Multiple Languages in One Source File Page 288 G2. Obvious Behavior Is Unimplemented Page 288 G3. Incorrect Behavior at the Boundaries Page 289 G4. Overridden Safeties Page 289 G5. Duplication Page 289 G6. Code at Wrong Level of Abstraction Page 290 G7. Base Classes Depending on Their Derivatives Page 291 G8. Too Much Information Page 291 G9. Dead Code Page 292 G10. Vertical Separation Page 292 G11. Inconsistency Page 292 G12. Clutter Page 293 G13. Artificial Coupling Page 293 G14. Feature Envy Page 293 G15. Selector Arguments Page 294 G16. Obscured Intent Page 295 G17. Misplaced Responsibility Page 295 G18. Inappropriate Static Page 296 G19. Use Explanatory Variables Page 296 G20. Function Names Should Say What They Do Page 297 G21. Understand the Algorithm Page 297 G22. Make Logical Dependencies Physical Page 298 G23. Prefer Polymorphism to If/Else or Switch/Case Page 299 G24. Follow Standard Conventions Page 299 G25. Replace Magic Numbers with Named Constants Page 300 G26. Be Precise Page 301 G27. Structure over Convention Page 301 G28. Encapsulate Conditionals Page 301 G29. Avoid Negative Conditionals Page 302 G30. Functions Should Do One Thing Page 302 G31. Hidden Temporal Couplings Page 302 G32. Don't Be Arbitrary Page 303 G33. Encapsulate Boundary Conditions Page 304 G34. Functions Should Descend Only One Level of Abstraction Page 304 G35. Keep Configurable Data at High Levels Page 306 G36. Avoid Transitive Navigation Page 306 Java Page 307 J1. Avoid Long Import Lists by Using Wildcards Page 307 J2. Don't Inherit Constants Page 307 J3. Constants versus Enums Page 308 Names Page 309 N1. Choose Descriptive Names Page 309 N2. Choose Names at the Appropriate Level of Abstraction Page 311 N3. Use Standard Nomenclature Where Possible Page 311 N4. Unambiguous Names Page 312 N5. Use Long Names for Long Scopes Page 312 N6. Avoid Encodings Page 312 N7. Names Should Describe Side-Effects Page 313 Tests Page 313 T1. Insufficient Tests Page 313 T2. Use a Coverage Tool! Page 313 T3. Don't Skip Trivial Tests Page 313 T4. An Ignored Test Is a Question About an Ambiguity Page 313 T5. Test Boundary Conditions Page 314 T6. Exhaustively Test Near Bugs Page 314 T7. Patterns of Failure Are Revealing Page 314 T8. Test Coverage Patterns Can Be Revealing Page 314 T9. Tests Should Be Fast Page 314 Conclusion Page 314 Bibliography Page 315 Appendix A. Concurrency Page 317 Client/Server Example Page 317 The Server Page 317 Adding Threading Page 319 Server Observations Page 319 Conclusion Page 321 Possible Paths of Execution Page 321 Number of Paths Page 322 Digging Deeper Page 323 Conclusion Page 326 Knowing Your Library Page 326 Executor Framework Page 326 Nonblocking Solutions Page 327 Nonthread-Safe Classes Page 328 Dependencies Between Methods Can Break Concurrent Code Page 329 Tolerate the Failure Page 330 Client-Based Locking Page 330 Server-Based Locking Page 332 Increasing Throughput Page 333 Single-Thread Calculation of Throughput Page 334 Multithread Calculation of Throughput Page 335 Deadlock Page 335 Mutual Exclusion Page 336 Lock & Wait Page 337 No Preemption Page 337 Circular Wait Page 337 Breaking Mutual Exclusion Page 337 Breaking Lock & Wait Page 338 Breaking Preemption Page 338 Breaking Circular Wait Page 338 Testing Multithreaded Code Page 339 Tool Support for Testing Thread-Based Code Page 342 Conclusion Page 342 Tutorial: Full Code Examples Page 343 Client/Server Nonthreaded Page 343 Client/Server Using Threads Page 347 Appendix B. org.jfree.date.SerialDate Page 349 Appendix C. Cross References of Heuristics Page 409 Epilogue Page 411 Index Page 413