Clean Code TOC
2016.08.19
The table of contents of the book Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin, 1994). It is a good overview of the rules recommended by the book.
Clean Code
There Will Be Code
Bad Code
The Total Cost of Owning a Mess
The Grand Redesign in the Sky
Attitude
The Primal Conundrum
The Art of Clean Code?
What Is Clean Code?
Schools of Thought
We Are Authors
The Boy Scout Rule
Prequel and Principles
Conclusion
Bibliography
Meaningful Names
Introduction
Use Intention-Revealing Names
Avoid Disinformation
Make Meaningful Distinctions
Use Pronounceable Names
Use Searchable Names
Avoid Encodings
Hungarian Notation
Member Prefixes
Interfaces and Implementations
Avoid Mental Mapping
Class Names
Method Names
Don’t Be Cute
Pick One Word per Concept
Don’t Pun
Use Solution Domain Names
Use Problem Domain Names
Add Meaningful Context
Don’t Add Gratuitous Context
Final Words
Functions
Small!
Blocks and Indenting
Do One Thing
Sections within Functions
One Level of Abstraction per Function
Reading Code from Top to Bottom: The Stepdown Rule
Switch Statements
Use Descriptive Names
Function Arguments
Common Monadic Forms
Flag Arguments
Dyadic Functions
Triads
Argument Objects
Argument Lists
Verbs and Keywords
Have No Side Effects
Output Arguments
Command Query Separation
Prefer Exceptions to Returning Error Codes
Extract Try/Catch Blocks
Error Handling Is One Thing
The Error.java Dependency Magnet
Don’t Repeat Yourself
Structured Programming
How Do You Write Functions Like This?
Conclusion
SetupTeardownIncluder
Bibliography
Comments
Comments Do Not Make Up for Bad Code
Explain Yourself in Code
Good Comments
Legal Comments
Informative Comments
Explanation of Intent
Clarification
Warning of Consequences
TODO Comments
Amplification
Javadocs in Public APIs
Bad Comments
Mumbling
Redundant Comments
Misleading Comments
Mandated Comments
Journal Comments
Noise Comments
Scary Noise
Don’t Use a Comment When You Can Use a
Function or a Variable
Position Markers
Closing Brace Comments
Attributions and Bylines
Commented-Out Code
HTML Comments
Nonlocal Information
Too Much Information
Inobvious Connection
Function Headers
Javadocs in Nonpublic Code
Example
Bibliography
Formatting
The Purpose of Formatting
Vertical Formatting
The Newspaper Metaphor
Vertical Openness Between Concepts
Vertical Density
Vertical Distance
Vertical Ordering
Horizontal Formatting
Horizontal Openness and Density
Horizontal Alignment
Indentation
Dummy Scopes
Team Rules
Uncle Bob’s Formatting Rules
Objects and Data Structures
Data Abstraction
Data/Object Anti-Symmetry
The Law of Demeter
Train Wrecks
Hybrids
Hiding Structure
Data Transfer Objects
Active Record
Conclusion
Bibliography
Error Handling
Use Exceptions Rather Than Return Codes
Write Your Try-Catch-Finally Statement First
Use Unchecked Exceptions
Provide Context with Exceptions
Define Exception Classes in Terms of a Caller’s Needs
Define the Normal Flow
Don’t Return Null
Don’t Pass Null
Conclusion
Bibliography
Boundaries
Using Third-Party Code
Exploring and Learning Boundaries
Learning log4j
Learning Tests Are Better Than Free
Using Code That Does Not Yet Exist
Clean Boundaries
Bibliography
Unit Tests
The Three Laws of TDD
Keeping Tests Clean
Tests Enable the -ilities
Clean Tests
Domain-Specific Testing Language
A Dual Standard
One Assert per Test
Single Concept per Test
F.I.R.S.T
Conclusion
Bibliography
Classes
Class Organization
Encapsulation
Classes Should Be Small!
The Single Responsibility Principle
Cohesion
Maintaining Cohesion Results in Many Small Classes
Organizing for Change
Isolating from Change
Bibliography
Systems
How Would You Build a City?
Separate Constructing a System from Using It
Separation of Main
Factories
Dependency Injection
Scaling Up
Cross-Cutting Concerns
Java Proxies
Pure Java AOP Frameworks
AspectJ Aspects
Test Drive the System Architecture
Optimize Decision Making
Use Standards Wisely, When They Add DemonstrableValue
Systems Need Domain-Specific Languages
Conclusion
Bibliography
Emergence
Getting Clean via Emergent Design
Simple Design Rule 1: Runs All the Tests
Simple Design Rules 2–4: Refactoring
No Duplication
Expressive
Minimal Classes and Methods
Conclusion
Bibliography
Concurrency
Why Concurrency?
Myths and Misconceptions
Challenges
Concurrency Defense Principles
Single Responsibility Principle
Corollary: Limit the Scope of Data
Corollary: Use Copies of Data
Corollary: Threads Should Be as Independent as Possible
Know Your Library
Thread-Safe Collections
Know Your Execution Models
Producer-Consumer
Readers-Writers
Dining Philosophers
Beware Dependencies Between Synchronized Methods
Keep Synchronized Sections Small
Writing Correct Shut-Down Code Is Hard
Testing Threaded Code
Treat Spurious Failures as Candidate Threading Issues
Get Your Nonthreaded Code Working First
Make Your Threaded Code Pluggable
Make Your Threaded Code Tunable
Run with More Threads Than Processors
Run on Different Platforms
Instrument Your Code to Try and Force Failures
Hand-Coded
Automated
Conclusion
Bibliography
Successive Refinement
Args Implementation
How Did I Do This?
Args: The Rough Draft
So I Stopped
On Incrementalism
String Arguments
Conclusion
JUnit Internals
The JUnit Framework
Conclusion
Refactoring SerialDate
First, Make It Work
Then Make It Right
Conclusion
Bibliography
Smells and Heuristics
Comments
Inappropriate Information
Obsolete Comment
Redundant Comment
Poorly Written Comment
Commented-Out Code
Environment
Build Requires More Than One Step
Tests Require More Than One Step
Functions
Too Many Arguments
Output Arguments
Flag Arguments
Dead Function
General
Multiple Languages in One Source File
Obvious Behavior Is Unimplemented
Incorrect Behavior at the Boundaries
Overridden Safeties
Duplication
Code at Wrong Level of Abstraction
Base Classes Depending on Their Derivatives
Too Much Information
Dead Code
Vertical Separation
Inconsistency
Clutter
Artificial Coupling
Feature Envy
Selector Arguments
Obscured Intent
Misplaced Responsibility
Inappropriate Static
Use Explanatory Variables
Function Names Should Say What They Do
Understand the Algorithm
Make Logical Dependencies Physical
Prefer Polymorphism to If/Else or Switch/Case
Follow Standard Conventions
Replace Magic Numbers with Named Constants
Be Precise
Structure over Convention
Encapsulate Conditionals
Avoid Negative Conditionals
Functions Should Do One Thing
Hidden Temporal Couplings
Don’t Be Arbitrary
Encapsulate Boundary Conditions
Functions Should Descend Only One Level of Abstraction
Keep Configurable Data at High Levels
Avoid Transitive Navigation
Java
Avoid Long Import Lists by Using Wildcards
Don’t Inherit Constants
Constants versus Enums
Names
Choose Descriptive Names
Choose Names at the Appropriate Level of Abstraction
Use Standard Nomenclature Where Possible
Unambiguous Names
Use Long Names for Long Scopes
Avoid Encodings
Names Should Describe Side-Effects.
Tests
Insufficient Tests
Use a Coverage Tool!
Don’t Skip Trivial Tests
An Ignored Test Is a Question about an Ambiguity
Test Boundary Conditions
Exhaustively Test Near Bugs
Patterns of Failure Are Revealing
Test Coverage Patterns Can Be Revealing
Tests Should Be Fast
Conclusion
Bibliography
Appendix A: Concurrency II
Client/Server Example
The Server
Adding Threading
Server Observations
Conclusion
Possible Paths of Execution
Number of Paths
Digging Deeper
Conclusion
Knowing Your Library
Executor Framework
Nonblocking Solutions
Nonthread-Safe Classes
Dependencies Between Methods
Can Break Concurrent Code
Tolerate the Failure
Client-Based Locking
Server-Based Locking
Increasing Throughput
Single-Thread Calculation of Throughput
Multithread Calculation of Throughput
Deadlock
Mutual Exclusion
Lock & Wait
No Preemption
Circular Wait
Breaking Mutual Exclusion
Breaking Lock & Wait
Breaking Preemption
Breaking Circular Wait
Testing Multithreaded Code
Tool Support for Testing Thread-Based Code
Conclusion
Tutorial: Full Code Examples
Client/Server Nonthreaded
Client/Server Using Threads
Appendix B: org.jfree.date.SerialDate
Appendix C: Cross References of Heuristics
Epilogue
Last updated