More on this book
Community
Kindle Notes & Highlights
Read between
April 20 - July 17, 2019
In software, 80% or more of what we do is quaintly called “maintenance”: the act of repair.
Making your code readable is as important as making it executable.
Back in my days working in the Bell Labs Software Production Research organization (Production, indeed!) we had some back-of-the-envelope findings that suggested that consistent indentation style was one of the most statistically significant indicators of low bug density.
Quality is the result of a million selfless acts of care—not just of any great method that descends from the heavens.
We should view our code as the beautiful articulation of noble efforts of design—design as a process, not a static endpoint.
It is a recommended practice in Scrum that re-factoring be part of the concept of “Done.”
Over the span of a year or two, teams that were moving very fast at the beginning of a project can find themselves moving at a snail’s pace.
spending time keeping your code clean is not just cost effective; it’s a matter of professional survival.
So too it is unprofessional for programmers to bend to the will of managers who don’t understand the risks of making messes.
All developers with more than a few years experience know that previous messes slow them down. And yet all developers feel the pressure to make messes in order to meet deadlines. In short, they don’t take the time to go fast!
The only way to make the deadline—the only way to go fast—is to keep the code as clean as possible at all times.
being able to recognize clean code from dirty code does not mean that we know how to write clean code!
Wasted cycles are inelegant, they are not pleasing.
Bad code tempts the mess to grow! When others change bad code, they tend to make it worse.
The upshot is that clean code exhibits close attention to detail.
Clean code is focused. Each function, each class, each module exposes a single-minded attitude that remains entirely undistracted, and unpolluted, by the surrounding details.
clean code should read like well-written prose.
Dave asserts that clean code makes it easy for other people to enhance it.
Code, without tests, is not clean.
Clean code always looks like it was written by someone who cares.
It is not the language that makes programs appear simple. It is the programmer that make the language appear simple!
the ratio of time spent reading vs. writing is well over 10:1. We are constantly reading old code as part of the effort to write new code.
The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent.
One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king.
When constructors are overloaded, use static factory methods with names that describe the arguments.
A consistent lexicon is a great boon to the programmers who must use your code.
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.
The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that.
This implies that the blocks within if statements, else statements, while statements, and so on should be one line long. Probably that line should be a function call.
the indent level of a function should not be greater than one or two.
FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL. THEY SHOULD DO IT ONLY.
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.
Functions that do one thing cannot be reasonably divided into sections.
Mixing levels of abstraction within a function is always confusing. Readers may not be able to tell whether a particular expression is an essential concept or a detail.
We want the code to read like a top-down narrative.
Making the code read like a top-down set of TO paragraphs is an effective technique for keeping the abstraction level consistent.
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
Ward’s principle: “You know you are working on clean code when each routine turns out to be pretty much what you expected.”
A long descriptive name is better than a long descriptive comment.
It is not at all uncommon that hunting for a good name results in a favorable restructuring of the code.
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.
A somewhat less common, but still very useful form for a single argument function, is an event.
It should be very clear to the reader that this is an event. Choose names and contexts carefully.
Flag arguments are ugly. Passing a boolean into a function is a truly terrible practice.
The second requires a short pause until we learn to ignore the first parameter. 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.
Dyads aren’t evil, and you will certainly have to write them. However, you should be aware that they come at a cost and should take advantage of what mechanisms may be available to you to convert them into monads.
I suggest you think very carefully before creating a triad.
When groups of variables are passed together, the way x and y are in the example above, they are likely part of a concept that deserves a name of its own.
In general output arguments should be avoided. If your function must change the state of something, have it change the state of its owning object.
