Clean Code: chapter 1~5

 

you should try several different names and read the code with each in place .

 

here the in place is key point. it asks people to consider better names, don't be afraid to spend more time, cuz it's worth that. in place means in proper place, it's an important usage.

 

Modern IDEs like Eclipse or IntelliJ make it trivial to change names.

 

here the usage of trivial by make it trivial to do sth is rare to see, means easy, right? with the help of modern IDEs, it's rather easy to change a whole bunch of the same names.

 

2011.04.06

the following is a pretty classic English paragraph from the first of the 5th chapter.

 

When people look under the hood, we want them to be impressed with the neatness, consistency,
and attention to detail that they perceive. We want them to be struck by the
orderliness. We want their eyebrows to rise as they scroll through the modules. We want
them to perceive that professionals have been at work. If instead they see a scrambled
mass of code that looks like it was written by a bevy of drunken sailors, then they are
likely to conclude that the same inattention to detail pervades every other aspect of the
project.

 

Code formatting is about communication, and communication is the professional developer’s first order of business .

 

Perhaps you thought that “getting it working” was the first order of business for a
professional developer. I hope by now, however, that this book has disabused you of that
idea. The functionality that you create today has a good chance of changing in the next
release, but the readability of your code will have a profound effect on all the changes
that will ever be made. The coding style and readability set precedents that continue to
affect maintainability and extensibility long after the original code has been changed
beyond recognition. Your style and discipline survives, even though your code does not.

 

here uncle bob continues to emphasize and prove why communication i.e. formatting style is so important?

readability of the code is preferrable to getting it working. and beyond recognition means your code has been changed a lot and it's beyond recognition. so your style and discipline survives, even though your code does not.

 

But we’re not trying for precision here. We’re just trying to get a feel.

 

Seven different projects are depicted .

 

What does that mean to us? It appears to be possible to build significant systems
(FitNesse is close to 50,000 lines) out of files that are typically 200 lines long, with an
upper limit of 500. Although this should not be a hard and fast rule, it should be considered
very desirable. Small files are usually easier to understand than large files are.

 

As you continue downward, the details increase until you have all the dates, names, quotes, claims, and other minutia.

 

A newspaper is composed of many articles; most are very small. Some are a bit larger .
Very few contain as much text as a page can hold . This makes the newspaper usable. If the
newspaper were just one long story containing a disorganized agglomeration of facts,
dates, and names, then we simply would not read it.

 

As you scan down the listing, your eye is drawn to the first line that follows a blank line.

 

Taking those blank lines out, as in Listing 5-2, has a remarkably obscuring effect on the
readability of the code.

 

This effect is even more pronounced when you unfocus your eyes. In the first example
the different groupings of lines pop out at you, whereas the second example looks like a
muddle. The difference between these two listings is a bit of vertical openness.

 

We want to avoid forcing our readers to hop around through our source files and classes.

 

Dependent Functions. If one function calls another, they should be vertically close,
and the caller should be above the callee, if at all possible. This gives the program a natural
flow. If the convention is followed reliably, readers will be able to trust that function definitions
will follow shortly after their use. Consider, for example, the snippet from FitNesse
in Listing 5-5. Notice how the topmost function calls those below it and how they in turn
call those below them. This makes it easy to find the called functions and greatly enhances
the readability of the whole module.

 

As an aside, this snippet provides a nice example of keeping constants at the appropriate
level [G35]. The "FrontPage" constant could have been buried in the
getPageNameOrDefault function, but that would have hidden a well-known and expected
constant in an inappropriately low-level function. It was better to pass that constant down
from the place where it makes sense to know it to the place that actually uses it.

 

String pageName = getPageNameOrDefault(request, "FrontPage");

private String getPageNameOrDefault(Request request, String defaultPageName) {
    String pageName = request.getResource();
    if (StringUtil.isBlank(pageName))
        pageName = defaultPageName;
    return pageName;
}

 

pass that constant down (means from high level to low level) where it makes sense to know it (the caller place) to the place that actually uses it (the function body)

 

These functions have a strong conceptual affinity because they share a common naming
scheme and perform variations of the same basic task. The fact that they call each other is
secondary. Even if they didn’t, they would still want to be close together.

 

As in newspaper articles, we expect the most important concepts to come first, and
we expect them to be expressed with the least amount of polluting detail. We expect the
low-level details to come last. This allows us to skim source files, getting the gist from the

first few functions, without having to immerse ourselves in the details.

 

Remember this is a log scale, so the linear appearance of the drop-off above 80 characters
is really very significant. Programmers clearly prefer short lines.

 

I used to follow the rule that you should never have to scroll to the right. But monitors
are too wide for that nowadays, and younger programmers can shrink the font so small that they can get 200 characters across the screen. Don’t do that. I personally set my limit at 120.

 

Whenever I have succumbed to this temptation, I have almost always gone back and put the indentation back in.

 

Then we encoded those rules into the code formatter of our IDE and have stuck with them ever since.

 

Remember, a good software system is composed of a set of documents that read nicely. They need to have a consistent and smooth style.

 

The last thing we want to do is add more complexity to the source code by writing it in a jumble of different individual styles.

 

here the the last thing roughly means the thing one should not do