Notes of Clean Code from Uncle Bob

這是一篇不完整的 Clean Code — Uncle Bob 速記，內文請與影片搭配使用。

Lesson 1

Function

1. Function name as noun is terrible idea, should be verb, cause functions do things
2. Every line of a function should be at the same level of abstraction and that level should be one below the name (一個函式內僅有一種等級的物件，函式第一行物件即是該等級)
3. Smaller (smaller block, shorter name) is better
4. headline(all high level terms)→ abstract(slightly more detailed) → and increasing details until we get the bottom
   Allow the reader to escape early
   How do people read news?

Do one thing

1. how small it need to be? a function should do one thing. The one thing should be you can’t meaningfully extract another function from it.
2. Sink in the sea of tiny little functions?No, you won’t. Name it properly.
3. “Class” consists of extracted functions that manipulate a set of variables.
4. The indent level of as function should not be greater than one or two(as the function would be large to have nests)

Arguments

1. A function more than 3 args is too complicated!
2. To much args → should be a object or contained
3. Don’t pass boolean variable into functions!
4. Don’t pass a “output args” for collecting outputs.
5. Code make you “double take” is rude, make sure your code is not surprising.

Avoid switch statements

1. Avoid switch statements, use Polymorphism.
2. Open close principle: open for extensions, close for modifications.
3. switch statement may result in a large amount of recompiling.
4. 1:23:55 linking and loading

No side-effects

1. Side-effects pairs things should be finished in one function.
2. Convention:
   Command(return void) must have a side effect
   Query(return value) doesn’t

Exception, not returning error code

Don’t repeat your self

1. For multiple loop, JAVA lambda is a solution.

Structured Programming

1. Why did Dijkstra not want go-to
2. We don’t prove software correct like math, but we test it not incorrect like science.

Lesson 2

Comments

1. Comments are used to explain code if the code can’t explain itself.
2. Comments are not “pure good”, a comment is a failure for explain code by itself
3. Comments silently rot.
4. Write Bad code → Don’t comment it → Clean it!
5. If you can’t clean it, then comment it.
6. Always use name to explain code first, not comments.
7. Know Design Pattern!
8. Comments for DP could be informative
9. Comments for regex could be informative
10. Javados(like pydoc) are good, but they can lie.

Bad comments

1. Don’t mumbling to yourself with comments(what comments say should be very valid, local and simple.)
2. Don’t comment if code is simpler than the comment.
3. The place make the comments most readable is in the code, not HTML with Javadocs.

Format

1. number of line in File, Avg. 50 lines, most of files are within 100 lines, probably be good.
2. length of a line, 30–40 is probably good and shorter than 80.

Naming

1. A name that requires a comment, does not reveal it’s intent.
2. How long should a name be?
   Variable: small scope, short name; large scope, long name.
   Function, Class: large scope, short name; vice versa.
3. Naming need to be disambiguated
4. Avoid situations where code will break if a spelling error is fixed
5. data vs dataProduct vs pd vs aProduct vs theProduct vs productInfo
6. getActiveAccount vs getActiveAccounts vs getActiveAccountInfo, which fn to call?

Lesson 3

I am your new CTO

Don’t ship shit.

1. When you release code, you will know it works, don’t guess it.

We will always be ready

1. Shorter sprint length might be better, cause we document well, test it, integrate it more frequently, and is ready to deploy it.
2. shippable, deployable, deliverable

Stable productivity

1. the longer the project goes, the slower you don’t get
2. if you do, because something is a mess

Inexpensive Adaptability

1. Be cheap and easy to make changes to the system. the cost of the change = k × the scope of the change
2. soft ware = changable product, if not , it’s hardware

Continuous Improvement of the system

1. code to get better with time.

Fearless Competence

1. if code need to clean, clean it, don’t leave it.Test it.
2. Get green little test buttom

QA will(should) find nothing.

1. Let QA automated

We cover for each other

1. how to make sure someone can cover for you? pairing, so code reviewing might consider to cancel

Honest Estimates

1. define the shape of what we don’t know
2. 3 number: best case, nominal case, worst case

Lesson 4

You will say “no”

Test-driven development

1. Don’t write code until you write a test that fails, because the code doesn’t exist.
2. Don’t write more of a test that is sufficient to fail and “not compiling” is the failure.
3. Don’t write code that is sufficient to pass the failing test.
4. Test but don’t debug
5. Test code is the code example
6. testable ←→ decoupled
7. TDD is double entry bookkeeping, they both do it twice.
8. Mutation test
9. Production code → more general, Test code → more specific
10. Don’t run into the gold when writing test code, as long as you can.
11. Learn TDD externally at first.

Lesson 5

1. Architecture does not emerge from nothing.
2. Shape of Architectures might change, not fixed.

Goal

1. Software Architect is to minimize the human resources required to build and maintain software systems.
2. Measure of quality = k / Measure of efforts to meet requirement(inverse proportion)