Book notes: Clean Code - Chapters 1-4
Tags: books
Published: 2021-01-27 02:31:42

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