Skip to content

Latest commit

 

History

History
82 lines (71 loc) · 4 KB

README.md

File metadata and controls

82 lines (71 loc) · 4 KB
Raw

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

  • 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!