Clean code:a handbook of agile software craftsmanship

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

avoid encodings　23

hungarian notation　23

member prexes　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 errorjava 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

clarication　57

warning of consequences　58

todo comments　58

amplication　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

dene exception classes in terms of a caller’s needs　107

dene 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-specic testing language　127

a dual standard　127

one assert per test　130

single concept per test　131

first　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-specic 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

makeyour 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 renement　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: articial 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 congurable 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: insufcient 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: orgjfreedateserialdate　349

appendix c: cross references of heuristics　409

epilogue　411

index　413