Clean Code Collection - Robert C. Martin

Date: 2022-04-16
| piece of code should be where you expect to find it—and, if not,
| you should re-factor to get it there
Chapter: Foreword


Date: 2022-04-16
| Design is ever ongoing not only as we add a new room to a house,
| but as we are attentive to repainting, replacing worn carpets,
| or upgrading the kitchen sink
Chapter: Foreword


Date: 2022-04-16
| And while rework in the manufacturing metaphor leads to cost,
| rework in design leads to value. We should view our code as the
| beautiful articulation of noble efforts of design—design as a
| process, not a static endpoint
Chapter: Foreword


Date: 2022-04-19
| Most managers want good code, even when they are obsessing about
| the schedule. They may defend the schedule and requirements with
| passion; but that’s their job. It’s your job to defend the code
| with equal passion
Chapter: 1 Clean Code


Date: 2022-04-20
| The problem isn’t the simplicity of the code but the implicity
| of the code (to coin a phrase): the degree to which the context is
| not explicit in the code itself
Chapter: 2 Meaningful Names


Date: 2022-04-20
| Noise words are another meaningless distinction. Imagine that you
| have a Product class. If you have another called ProductInfo or
| ProductData, you have made the names different without making them
| mean anything different. Info and Data are indistinct noise words
| like a, an, and the.
Chapter: 2 Meaningful Names


Date: 2022-04-20
| 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
Chapter: 2 Meaningful Names


Date: 2022-04-20
| We want our code to be a quick skim, not an intense study. We want
| to use the popular paperback model whereby the author is responsible
| for making himself clear and not the academic model where it is
| the scholar’s job to dig the meaning out of the paper
Chapter: 2 Meaningful Names


Date: 2022-04-20
| problem domain
Chapter: 2 Meaningful Names


Date: 2022-04-20
| Separating solution and problem domain concepts is part of the
| job of a good programmer and designer. The code that has more to
| do with problem domain concepts should have names drawn from the
| problem domain
Chapter: 2 Meaningful Names


Date: 2022-04-20
| public String make
Chapter: 2 Meaningful Names


Date: 2022-04-20
| People are also afraid of renaming things for fear that some other
| developers will object. We do not share that fear and find that we
| are actually grateful when names change (for the better
Chapter: 2 Meaningful Names


Date: 2022-04-20
| FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL. THEY SHOULD
| DO IT ONLY
Chapter: 3 Functions


Date: 2022-04-20
| The problem with this statement is that it is hard to know what
| “one thing” is
Chapter: 3 Functions


Date: 2022-04-20
| We could extract the if statement into a function named
| includeSetupsAndTeardownsIfTestPage, but that simply restates the
| code without changing the level of abstraction.  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
Chapter: 3 Functions


Date: 2022-04-21
| Mixing levels of abstraction within a function is always confusing
Chapter: 3 Functions


Date: 2022-04-21
| 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 [G23
Chapter: 3 Functions


Date: 2022-06-08
| Employee and Factory
Chapter: 3 Functions


Date: 2022-04-21
| 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
Chapter: 3 Functions


Date: 2022-04-21
| And that, of course, eventually results in problems because we
| should never ignore any part of code. The parts we ignore are where
| the bugs will hide
Chapter: 3 Functions


Date: 2022-04-21
| When a function seems to need more than two or three arguments,
| it is likely that some of those arguments ought to be wrapped into
| a class of their own
Chapter: 3 Functions


Date: 2022-04-21
| Temporal couplings are confusing, especially when hidden as a side
| effect. If you must have a temporal coupling, you should make it
| clear in the name of the function. In this case we might rename the
| function checkPasswordAndInitializeSession, though that certainly
| violates “Do one thing
Chapter: 3 Functions


Date: 2022-04-23
| Functions should either do something or answer something, but
| not both
Chapter: 3 Functions


Date: 2022-04-23
| Returning error codes from command functions is a subtle violation
| of command query separation. It promotes commands being used as
| expressions in the predicates of if statements
Chapter: 3 Functions


Date: 2022-04-23
| Some programmers follow Edsger Dijkstra’s rules of structured
| programming.14 Dijkstra said that every function, and every block
| within a function, should have one entry and one exit. Following
| these rules means that there should only be one return statement in
| a function, no break or continue statements in a loop, and never,
| ever, any goto statements
Chapter: 3 Functions


Date: 2022-04-23
| Writing software is like any other kind of writing. When you write
| a paper or an article, you get your thoughts down first, then you
| massage it until it reads well. The first draft might be clumsy and
| disorganized, so you wordsmith it and restructure it and refine it
| until it reads the way you want it to read.  When I write functions,
| they come out long and complicated. They have lots of indenting
| and nested loops. They have long argument lists. The names are
| arbitrary, and there is duplicated code. But I also have a suite
| of unit tests that cover every one of those clumsy lines of code.
| So then I massage and refine that code, splitting out functions,
| changing names, eliminating duplication. I shrink the methods and
| reorder them. Sometimes I break out whole classes, all the while
| keeping the tests passing.  In the end, I wind up with functions
| that follow the rules I’ve laid down in this chapter. I don’t
| write them that way to start. I don’t think anyone could.
Chapter: 3 Functions


Date: 2022-04-23
| Master programmers think of systems as stories to be told rather
| than programs to be written
Chapter: 3 Functions


Date: 2022-04-23
| So when you find yourself in a position where you need to write a
| comment, think it through and see whether there isn’t some way to
| turn the tables and express yourself in code. Every time you express
| yourself in code, you should pat yourself on the back. Every time
| you write a comment, you should grimace and feel the failure of
| your ability of expression
Chapter: 4 Comments


Date: 2022-04-23
| Rather than spend your time writing the comments that explain the
| mess you’ve made, spend it cleaning that mess
Chapter: 4 Comments


Date: 2022-04-23
| It takes only a few seconds of thought to explain most of your
| intent in code. In many cases it’s simply a matter of creating
| a function that says the same thing as the comment you want to write
Chapter: 4 Comments


Date: 2022-04-23
| Keep in mind, however, that the only truly good comment is the
| comment you found a way not to write
Chapter: 4 Comments


Date: 2022-04-25
| commented-out code gathers like dregs at the bottom of a bad bottle
| of wine
Chapter: 4 Comments


Date: 2022-04-25
| The purpose of a comment is to explain code that does not explain
| itself. It is a pity when a comment needs its own explanation
Chapter: 4 Comments


Date: 2022-04-25
| Concepts that are closely related should be kept vertically close
| to each other
Chapter: 5 Formatting


Date: 2022-05-02
| Hiding implementation is about abstractions! A class does not
| simply push its variables out through getters and setters. Rather
| it exposes abstract interfaces that allow its users to manipulate
| the essence of the data, without having to know its implementation.
Chapter: 6 Objects and Data Structures


Date: 2022-05-02
| We do not want to expose the details of our data. Rather we want
| to express our data in abstract terms
Chapter: 6 Objects and Data Structures


Date: 2022-05-02
| Objects hide their data behind abstractions and expose functions
| that operate on that data. Data structure expose their data and
| have no meaningful functions
Chapter: 6 Objects and Data Structures


Date: 2022-05-04
| Objects expose behavior and hide data. This makes it easy to add new
| kinds of objects without changing existing behaviors. It also makes
| it hard to add new behaviors to existing objects. Data structures
| expose data and have no significant behavior. This makes it easy
| to add new behaviors to existing data structures but makes it hard
| to add new data structures to existing functions
Chapter: 6 Objects and Data Structures


Date: 2022-05-13
| The problem is that too many of us think that we are done once the
| program works. We fail to switch to the other concern of organization
| and cleanliness. We move on to the next problem rather than going
| back and breaking the overstuffed classes into decoupled units with
| single responsibilities
Chapter: 10 Classes


Date: 2022-05-13
| At the same time, many developers fear that a large number of small,
| single-purpose classes makes it more difficult to understand the
| bigger picture. They are concerned that they must navigate from
| class to class in order to figure out how a larger piece of work
| gets accomplished.
Chapter: 10 Classes


Date: 2022-05-13
| However, a system with many small classes has no more moving parts
| than a system with a few large classes. There is just as much to
| learn in the system with a few large classes. So the question is:
| Do you want your tools organized into toolboxes with many small
| drawers each containing well-defined and well-labeled components? Or
| do you want a few drawers that you just toss everything into
Chapter: 10 Classes


Date: 2022-05-28
| Dependency Inversion Principle (DIP).5 In essence, the DIP says that
| our classes should depend upon abstractions, not on concrete details.
| 5. [PPP].  Instead of being dependent upon the implementation
| details of the TokyoStock-Exchange class, our Portfolio class is
| now dependent upon the StockExchange interface. The StockExchange
| interface represents the abstract concept of asking for the current
| price of a symbol. This abstraction isolates all of the specific
| details of obtaining such a price, including from where that price
| is obtained
Chapter: 10 Classes


Date: 2022-05-28
| Software systems should separate the startup process, when the
| application objects are constructed and the dependencies are
| “wired” together, from the runtime logic that takes over after
| startup.
Chapter: 11 Systems


Date: 2022-05-28
| Professional developers learn to manage their time to take advantage
| of their focus-manna. We write code when our focus-manna is high;
| and we do other, less productive things when it’s not
Chapter: 9. Time Management


Date: 2022-05-28
| Focus-manna is also a decaying resource. If you don’t use it when
| it’s there, you are likely to lose
Chapter: 9. Time Management


Date: 2022-05-28
| Some people take the time to work with their hands. Perhaps they
| enjoy carpentry, or building models, or gardening. Whatever the
| activity, there is something about activities that focus on muscles
| that enhances the ability to work with your mind
Chapter: 9. Time Management


Date: 2022-05-28
| I find that I am most creative when I am exposed to other people’s
| creativity. So I read lots of science fiction. The creativity of
| those authors somehow stimulates my own creative juices for software
Chapter: 9. Time Management


Date: 2022-05-28
| Actually, we aren’t lying to ourselves. What we are really doing
| is preparing for the lie we’ll tell when someone asks us what
| we are doing and why we are doing it. We are building a defense to
| protect us from the judgment of others
Chapter: 9. Time Management


Date: 2022-05-28
| Professionals evaluate the priority of each task, disregarding their
| personal fears and desires, and execute those tasks in priority order
Chapter: 9. Time Management


Date: 2022-05-28
| But you can also continue to go forward. Going back looks expensive
| because you’ll have to rework the existing code, but going back
| will never be easier than it is now. If you go forward you will
| drive the system into a swamp from which it may never escape
Chapter: 9. Time Management


Date: 2022-05-28
| Professionals don’t make commitments unless they know they can
| achieve them. It’s really as simple as that. If you are asked
| to commit to something that you aren’t certain you can do, then
| you are honor bound to decline. If you are asked to commit to a
| date that you know you can achieve, but would require long hours,
| weekends, and skipped family vacations, then the choice is yours; but
| you’d better be willing to do what it takes.  Commitment is about
| certainty. Other people are going to accept your commitments and
| make plans based upon them. The cost of missing those commitments,
| to them, and to your reputation, is enormous. Missing a commitment
| is an act of dishonesty only slightly less onerous than an overt lie
Chapter: 10. Estimation


Date: 2022-05-30
| Choose disciplines that you feel comfortable following in a
| crisis. Then follow them all the time. Following these disciplines
| is the best way to avoid getting into a crisis.  Don’t change your
| behavior when the crunch comes. If your disciplines are the best way
| to work, then they should be followed even in the depths of a crisis
Chapter: 11. Pressure