Notes from "Clean Code": A Handbook of Agile Software Craftsmanship

Clean Code is an excellent book. Here are some notes I took while reading a few of the chapters online. (The rest I ended up reading on paper, so notes are not easy to share). All in all, the book is full of excellent advice.
The chapter on generics bares a special mention. It's clear, insightful and revolting at the same time. The revolting part comes from the clarify with which the whole ugly nature of Java generics implementation is exposed to the reader. So the blame for that lies with the authors of the implementation, not the book's! The book actually manages to make the muddy mess as clear as it can be.

Here are the notes

• ProQuest Information and Learning - 9780136083238 - Clean Code: A Handbook of Agile Software Craftsmanship
  • The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification—and then shouldn't be used anyway.
  • "You know you are working on clean code when each routine turns out to be pretty much what you expected." Half the battle to achieving that principle is choosing good names for small functions that do one thing.
  • Don't be afraid to make a name long. A long descriptive name is better than a short enigmatic name. A long descriptive name is better than a long descriptive comment.
  • The LOGO language used the keyword "TO" in the same way that Ruby and Python use "def." So every function began with the word "TO." This had an interesting effect on the way functions were designed.
  • There are two very common reasons to pass a single argument into a function. You may be asking a question about that argument, as in boolean fileExists("MyFile"). Or you may be operating on that argument, transforming it into something else and returning it. For example, InputStream fileOpen("MyFile") transforms a file name String into an InputStream return value.
    • The distinction is not too clear. A question is a special form of transformation? In both cases there is knowledge in the function about how to answer the question or transform the argument. But there are no side effects in either case (presumably).
  • My general rule for switch statements is that they can be tolerated if they appear only once, are used to create polymorphic objects, and are hidden behind an inheritance relationship so that the rest of the system can't see them
  • If a function does only those steps that are one level below the stated name of the function, then the function is doing one thing.
  • A somewhat less common, but still very useful form for a single argument function, is an event. In this form there is an input argument but no output argument. The overall program is meant to interpret the function call as an event and use the argument to alter the state of the system
    • So this modifies the state and that's the key differentiator? In otherwords, this function has side effects.
  • So, another way to know that a function is doing more than "one thing" is if you can extract another function from it with a name that is not merely a restatement of its implementation [G34].
  • Try to avoid any monadic functions that don't follow these forms, for example, void includeSetupPageInto(StringBuffer pageText). Using an output argument instead of a return value for a transformation is confusing.
    • Yes, but it's the key to reducing garbage production...

Posted from Diigo. The rest of my favorite links are here.