My Reading Notes from Clean Code by Robert C. Martin
Visit Amazon.com to learn more about Clean Code.
Chapter 1: Clean Code
1. Coders are responsible for bad code. Managers and marketers look to coders for the information they need to make promises and commitments. Users look to coders to validate the way the requirements will fit the system. Managers may defend the schedule and requirements with passion, but that’s their job. The coder’s job is to defend clean code with equal passion.
2. Beck’s Rules of Simple Code, in priority order:
- It runs all the tests.
- It contains no duplication.
- It expresses all the design ideas that are in the system.
- It minimizes the number of entities such as classes, methods, functions, etc.
3. Coders are authors. And one thing about authors is they expect to have readers. The next time you write a line of code, remember you are an author, writing for readers who will judge your effort.
4. It’s not enough to write code well. The code has to be kept clean over time.
5. Remember the “Boy Scout Rule”: Leave the [codebase] cleaner than you found it.
Chapter 2: Meaningful Names
1. Use intention-revealing names. The name of a variable, function, or class, should answer all the big questions. It should tell you:
- Why it exists?
- What does it do?
- How it is used?
2. If a name requires a comment, then the name does not reveal its intent.
3. Use pronounceable names, use searchable names, and add meaningful context.
4. Don’t be cute, don’t use puns, and don’t have cultural biases. Boring, yet informative names are the best.
5. Do not be afraid if other coders object with your naming conventions. We are grateful when names change (for the better). Most of the time readers don’t memorize names or words, instead they focus on what the code does.
6. Remember, you are an author and you have readers. Act like it.
Chapter 3: Functions
1. The first rule of functions is they should be small. The second rule is that they should be smaller than that.
2. Functions should not be large enough to hold nested structures. Therefore, the indent level of a function should not be greater than one or two.
3. Functions should do one thing. They should do it well. They should do it only.
4. The ideal number of arguments for a function is zero. Next comes one, then two. Three or more requires a very special justification.
5. Output arguments are harder to understand than input arguments.
6. Flag arguments are ugly. It loudly proclaims that this function does more than one thing. It does one thing if the flag is true and another if the flag is false!
7. Either your function should change the state of an object, or it should return some information about that object, but not both.
8. Try/ Catch blocks are ugly. It is better to extract the bodies of the blocks into their own functions.
Chapter 4: Comments
1. Don’t write comments for bad code. Instead, re-write the code.
- When you find yourself in a position where you need to write a comment, think it through and see if isn’t some way to turn the tables and express yourself better in code.
2. The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. And the reason is simple. Programmers can’t realistically maintain them. Code changes and evolves.
3. Clear and expressive code with few comments is far superior than cluttered and complex code with lots of comments.
4. Some comments are necessary or beneficial:
- Legal comments for corporate coding standards
- Informative comments when the code can’t be expressed via functions
- Warning of consequences
- TODO comments are sometimes reasonable as long as they are not an excuse to leave bad code in the system
5. Don’t use a comment when you can write an informative variable or function name
6. Don’t comment out code. No other coder who sees it will have the courage to delete it. They’ll think it is there for a reason.
7. Don’t put interesting historical discussions, irrelevant descriptions, or when code was last updated. That’s what Github is for.
Chapter 5: Formatting
1. When coders look under the hood, we want them to be impressed and see that professional coders have been working.
2. Code formatting is about communication, and communication is the professional developer’s first order of business.
3. A code module should read like a newspaper article.
- The name should be simple but explanatory and should be efficient to tell us whether we are in the right module.
- Detail should increase as we move downward
4. Use blank/ new lines as a visual cue that identifies a new and separate concept.
5. Variable declarations should be declared as close to their usage as possible.
6. Instance variables should be declared at the top of the class.
Chapter 6: Objects and Data Structures
1. Keep variables private.
2. Objects should expose behavior and hide data. This makes it easy to add new kinds of objects without changing existing behaviors.
Chapter 7: Error Handling
1. Error handling is important but if it obscures logic, it’s wrong.
2. Objects should expose behavior and hide data. This makes it easy to add new kings of objects without changing existing behaviors.
3. Each exception that you throw should provide enough context to determine the source and location of an error.
4. Don’t return Null in your error handling or pass Null.
5. Remember, clean code is readable and robust.
Chapter 8: Boundaries
1. Third-party code helps us get more functionality delivered in less time. It’s not our job to test third-party code, but it’s in our best interest to write tests for them.
2. Objects should expose behavior and hide data. This makes it easy to add new kings of objects without changing existing behaviors.
3. Each exception that you throw should provide enough context to determine the source and location of an error.
4. Don’t return Null in your error handling or pass Null.
5. Remember, clean code is readable and robust.
Chapter 9: Unit Tests
1. There are three laws to TDD (Test-Driven Development):
- First Law: You may not write production code until you’ve written a failing unit test.
- Second Law: You may not write more of a unit test than is sufficient to fail, and not compiling is failing.
- Third Law: You may not write more production code than is sufficient
2. It is unit tests that keep code flexible, maintainable, and reusable. So, having an automated suite of units that cover the production code is the key to keeping your design and architecture as clean as possible.
3. Remember, tests should be FIRST:
- Fast. Tests should run quickly.
- Independent. Tests should not depend on each other.
- Repeatable. Tests should be repeatable in any environment.
- Self-Validating. The tests should have a boolean output. They either pass or fail.
- Timely. The tests need to be written in a timely fashion. They should be written just before the production code that makes them pass.
Chapter 10: Classes
1. Similar to functions, the first rule of classes is that they should be small. The second rule of classes is that they should be smaller than that.
2. We should be able to write a brief description of the class in about 25 words, without using the words “if”, “and”, “or”, or “but”.
3. Single Responsibility Principle (SRP) states that a class or module should have one, and only one, responsibility/ reason to change.
4. SRP is one of the more important concepts in OO design.
5. We want our systems to be composed of many small classes, not a few large ones. Each small class encapsulates a single responsibility, has a single reason to change, and collaborates with a few others to achieve the desired system behaviors.
Chapter 11: Systems
1. Complexity kills. It sucks the life out of developers, it makes products difficult to plan, build, and test.
2. Software systems are unique compared to physical systems. Their architectures can grow incrementally, if we maintain the proper separation of concerns.
3. Use the simplest thing that can possibly work.
Chapter 12: Emergence
1. Many feel that Kent Beck’s four rules of Simple Design are of significant help in creating well-designed software. A design is simple if it:
- Runs all the tests
- Contains no duplication
- Expresses the intent of the programmer
- Minimizes the number of classes and methods
2. It’s easy to write code that we understand, because at the time we write it we’re deep in an understanding of the problem we’re trying to solve. Other maintainers of the code aren’t going to have so deep an understanding.
3. A primary goal of test is to act as documentation by example. Someone reading our tests should be able to get a quick understanding of what a class is all about.
3. Take a little pride in your programming workmanship. Spend a little time with of you functions and classes. Choose better names, split large functions into smaller functions, and generally take care of what you’ve created.
4. Care is a precious resource.
Chapter 13: Concurrency
1. Why concurrency? Concurrency is a decoupling strategy. It helps us decouple what gets done from when it gets done. Decoupling what from when can dramatically improve both throughput and structures of an application.
2. Currency Defense Principles:
- Single Responsibility Principle (SRP) states that a given method/class/component should have a single reason to change. Keep your concurrency-related code separate from other code.
- Corollary: Limit the Scope of Data. Take data encapsulation to heart. Severely limit the access of any data that may be shared.
- Corollary: Use Copies of Data. If there is an easy way to avoid sharing objects, the resulting code will be far less likely to cause problems.
- Corollary: Threads should be as independent as possible. Attempt to partition data into independent subsets than can be operated on by independent threads, possibly in different processors.
Chapter 14: Successive Refinement
1. It is not enough for code to work. Code that works is often badly broken. Programmers who satisfy themselves with merely working code are behaving unprofessionally.
2. The solution to bad code rotting away is to continuously keep your code as clean and simple as it can be.
Chapter 15: JUnit Internals
*Chapter 15 was primarily used for the author to critique example code written using the JUnit framework.
1. JUnit is one of the most famous of all Java frameworks. It is simple in conception, precise in definition, and elegant in implementation.
