Clean Code

Key takeaways

• Code is read far more often than it is written, so write for the reader
• Names should reveal intent so clearly that comments become almost unnecessary
• Functions should be small and do exactly one thing at one level of abstraction
• A comment is usually a confession that the code could not explain itself
• Leave every file a little cleaner than you found it, one small change at a time

Inside this bit

1. Code is written for people

   Picture a developer opening a file written two years ago by a colleague who has since left. Every variable is called data or temp, one function runs for 300 lines, and nobody dares to touch it.

2. Names carry the meaning

   The cheapest improvement you can make is a better name. A variable named d tells you nothing; a variable named daysSinceLastLogin tells you everything, and it removes the need for a comment.

3. Small functions that do one thing

   Martin's rule for functions is simple to state and hard to follow: they should be small, and then smaller than that. A function should do one thing, do it well, and do only that.

4. Comments are not a fix

   Many programmers are taught that good code is heavily commented. Martin pushes back.

5. Tests make cleaning safe

   Why do teams leave ugly code alone? Fear.

6. Put it to work

   This week, pick the file you dread opening and rename three variables so their purpose is obvious without a comment. Find one long function and split out a single well-named piece, keeping behaviour identical, and run the tests before and after.