arabsorkhi / clean-code-1

Notes on "Clean Code" by the venerable Robert C. Martin.

clean-code

In this repo you can find my notes for Clean Code as I read through it. This is primarily to act as a learning tool and reference for me but I hope others will find it beneficial as well. Other repos that were trying to do this were not organized well and had either too much or too little information. Here I will list the handfull of notes I think most important for each section.

Sections

• Naming
• Functions
• Comments
• Formatting
• Objects vs. Data Structures
• Error Handling

Naming

• Change names when you find better ones
• A name should tell you why something exists, what it does, and how it is used
• The length of a name should correspond to the size of its scope
• Pick one word per abstract concept and stick with it (ex. get, retrieve, fetch are all equivalent so pick one)
• The author is responsible for making his code clear
• Add prefixes as a last resort
• View More

Functions

• Keep very small (hopefully < ~10 lines)
• Do a single thing
• The "thing" a function is doing should include steps one level of abstraction below the name of the function
• Code should read like a top-down narrative. Each level of abstraction leads to the next.
• Long and descriptive function names are acceptable
• Keep function arguments between 0 and 3
• Keep functions pure (no side-effects!)
• Functions should either do something or answer something, but not both.
• Don't repeat yourself
• View More

Comments

• Comments are for compensating for our lack of ability to express ourselves in code
• Comments are hard to maintain, think hard before you add some
• Inaccurate comments are far worse than no comments
• Don't leave commented out code. Others will be confused and afraid to remove it.
• Connection between the code and it's comment should be obvious
• Comments shouldn't need their own explanation
• A good function name is usually better than a comment header
• View More

Formatting

• Stick to a common set of style rules
• Style and discipline survives even if your code doesn't
• Try and keep files between 200 and 500 lines
• Vertical Formatting - High to low-level, separate groups of related lines by a blank line, tightly-related code should be vertically dense
• Caller functions should be above their callees (ideally). This gives the program a natural flow.
• Low-level functions should come last
• Keep lines short (~120 characters)
• Use horizontal whitespace to associate strongly related things
• View More

Objects vs. Data Structures

• Hiding implementation is about abstraction
• Abstraction allows manipulatin of the essence of the data, without having to know it's implementation
• Seriously think about best way to represent the data an object contains
• Objects hide their data behind abstractions and expose functions that operate on that data
• Data Structures expose their data and have no meanigful functions
• "A module should not know about the innard of the objects it manipulates" - (Law of Demeter)
• Example of a "Train Wreck" String outputDir = ctxt.getOptions().getScratchDir().getAbsolutePath();
• View More

Error Handling

• Keep error handling separate from logic
• Throw exceptions vs. returning error codes
• Stack traces can't tell you the intent of the failed operation
• Pass helpful error messages with your exceptions
• Wrap 3rd-party APIs - makes it easier to switch and aren't tied to a vendor's API choices
• The Special Case Pattern
• Don't return or pass null
• Treat error handling as a separate concern!