Book notes: Clean Code - Chapters 1-4

Hello folks!

I am starting a new series of posts about the books I am reading, these will be my notes on the book

I thought about reading the entire book before publishing any notes, but I think this would take a long time, and if anyone has feedback, it would make the cycle bigger than it could be.

So I will publish my notes as I read the book.

The book I am currently reading is Clean Code, an absolute must-read in our profession, I am sure most people that will read this have already read the book, but I hope I can help these people remember its content.

Structure

This is how I've structured my notes

Notes

• first note
• second note

...

• n note

Direct quotes

This is a quote (not really)

Others

Everything that is not a quote or a not is a personal thought

Notes

Chapter 1 - Clean Code

• Good code matters (obviously)
• It's our responsibility as developers to communicate the risks of having a bad code to business people

"Code, without tests, is not clean. No matter how elegant it is"

• We should leave the code cleaner than when we've checked it out

Chapter 2 - Meaningful Names

• Avoid meaningless names like "a", "a1", "b"
• Avoid noise words like "Data" or "Info"
• The length of a variable name should correspond to the size of its scope

"There can be no worse reason for using the name c than because a and b were already taken."

I laughed hard at this^

"One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king. Professionals use their powers for good and write code that others can understand."

"Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser"

• Pick one word per concept, don't use "get" and "fetch" for the same thing
• Pick one concept per word, don't use "get" for both fetching and retrieving properties
• People who will read our code are programmers, so we should use technical names over domain names; Ideally, the name will express both technical usage and domain
• Add meaningful context; Using prefixes, namespaces, objects to hold information and with the name of other variables
• Don't add meaningless context; Don't prefix every single variable in your application with its name
• Shorter names are better when they are clear enough

Chapter 3 - Functions

• Functions should be small, as small as possible
• Functions should not hold nested structures; if, else and loops should have only one line, and if more is necessary, this should be a function call with a descriptive name
• Functions should only do one thing and deal with abstraction only one level below its name;
• If a function does only steps one level below of abstraction, it is only doing one thing; After all, we write functions to decompose large concepts

"Functions that do one thing cannot be reasonably divided into sections"

• Functions should as few arguments as possible, having a lot of arguments make a function trickier to test
• Monadic functions (functions with 1 argument) should have two forms, you either ask a question to a function with its argument, and it has a return value that is that argument transformed, or you should have no return value and the function should change the state of the system
• Passing booleans to a monadic is a bad practice, if you are doing it, you probably should split that function in two
• When a function needs more than two arguments, you can likely wrap then into an object
• Functions should have no side effects

"Side effects are lies. Your function promises to do one thing, but it also does other hidden things."

• Functions should either do something or return something but not both
• We should use exceptions instead of returning error codes; When we return errors, we have to deal with them immediately, when we throw exceptions, we can deal with them later
• Try/catch blocks should each call their own functions

"Error handling is one thing"

Therefore, if we want our functions to do one thing, a function that handles errors should do only that

Chapter 4 - Comments

"Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them"

• Before writing a comment, we should before try to better express ourselves through code

^ This thing he says about comments is very important, he comes back to it a lot.

• If a comment is not maintained with the code, sooner or later, it will be lying about the nature of the function or class it is talking about
• Lying comments are worst than no comment at all

"It is possible to make the point that programmers should be disciplined enough to keep the comments in a high state of repair, relevance, and accuracy. I agree, they should. But I would rather that energy go toward making the code so clear and expressive that it does not need the comments in the first place."

• It is fine to write comments warning other developers of the possible consequences of using or changing a function
• It is fine to leave some TODO comments. But you should regularly try to eliminate them (implementing the changes they describe)
• Redundant comments are bad //and useless
• Mandated comments are bad, don't tell other programmers to write huge comment headers for each function if the functions themselves are expressive and clear enough
• Journal/log comments are bad, this kind of comment should be kept in commit messages
• Comments announcing the start or the end of a subject are bad, unless you use them rarely and meaningfully
• Comments announcing the end of a subject or a function are bad
• Commented-out code is bad
• Comments should be located near the code they talk about, this makes the maintaining of such comment easier
• Comments should not have a lot of information