eeymoo/Clean-Code-zh
1
0
Fork 0
mirror of https://github.com/glen9527/Clean-Code-zh.git synced 2025-12-17 18:54:23 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

标题 & 代码高亮

Browse Source
This commit is contained in:
gdut-yy
2019-12-28 22:27:33 +08:00
parent 67f3f67fac
commit 893fb65d8c
17 changed files with 684 additions and 682 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
docs/ch4.md
View File

@@ -1,4 +1,4 @@
Comments
# 第 4 章 Comments
Image
Image
@@ -17,7 +17,7 @@ So when you find yourself in a position where you need to write a comment, think
Why am I so down on comments? Because they lie. Not always, and not intentionally, but too often. The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. The reason is simple. Programmers can’t realistically maintain them.
Code changes and evolves. Chunks of it move from here to there. Those chunks bifurcate and reproduce and come together again to form chimeras. Unfortunately the comments don’t always follow them—can’t always follow them. And all too often the comments get separated from the code they describe and become orphaned blurbs of ever-decreasing accuracy. For example, look what has happened to this comment and the line it was intended to describe:
```java
MockRequest request;
private final String HTTP_DATE_REGEXP =
“[SMTWF][a-z]{2}\\,\\s[0-9]{2}\\s[JFMASOND][a-z]{2}\\s”+
@@ -27,7 +27,7 @@ Code changes and evolves. Chunks of it move from here to there. Those chunks bif
private FileResponder responder;
private Locale saveLocale;
// Example: ”Tue, 02 Apr 2003 22:18:49 GMT”
```
Other instance variables that were probably added later were interposed between the HTTP_DATE_REGEXP constant and it’s explanatory comment.
It is possible to make the point that programmers should be disciplined enough to keep the comments in a high state of repair, relevance, and accuracy. I agree, they should. But I would rather that energy go toward making the code so clear and expressive that it does not need the comments in the first place.
@@ -43,15 +43,15 @@ Clear and expressive code with few comments is far superior to cluttered and com
EXPLAIN YOURSELF IN CODE
There are certainly times when code makes a poor vehicle for explanation. Unfortunately, many programmers have taken this to mean that code is seldom, if ever, a good means for explanation. This is patently false. Which would you rather see? This:
```java
// Check to see if the employee is eligible for full benefits
if ((employee.flags & HOURLY_FLAG) &&
(employee.age > 65))
```
Or this?
```java
if (employee.isEligibleForFullBenefits())
```
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.
GOOD COMMENTS
@@ -61,31 +61,31 @@ Legal Comments
Sometimes our corporate coding standards force us to write certain comments for legal reasons. For example, copyright and authorship statements are necessary and reasonable things to put into a comment at the start of each source file.
Here, for example, is the standard comment header that we put at the beginning of every source file in FitNesse. I am happy to say that our IDE hides this comment from acting as clutter by automatically collapsing it.
```java
// Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.
// Released under the terms of the GNU General Public License version 2 or later.
```
Comments like this should not be contracts or legal tomes. Where possible, refer to a standard license or other external document rather than putting all the terms and conditions into the comment.
Informative Comments
It is sometimes useful to provide basic information with a comment. For example, consider this comment that explains the return value of an abstract method:
```java
// Returns an instance of the Responder being tested.
protected abstract Responder responderInstance();
```
A comment like this can sometimes be useful, but it is better to use the name of the function to convey the information where possible. For example, in this case the comment could be made redundant by renaming the function: responderBeingTested.
Here’s a case that’s a bit better:
```java
// format matched kk:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile(
“\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*”);
```
In this case the comment lets us know that the regular expression is intended to match a time and date that were formatted with the SimpleDateFormat.format function using the specified format string. Still, it might have been better, and clearer, if this code had been moved to a special class that converted the formats of dates and times. Then the comment would likely have been superfluous.
Explanation of Intent
Sometimes a comment goes beyond just useful information about the implementation and provides the intent behind a decision. In the following case we see an interesting decision documented by a comment. When comparing two objects, the author decided that he wanted to sort objects of his class higher than objects of any other.
```java
public int compareTo(Object o)
{
if(o instanceof WikiPagePath)
@@ -97,9 +97,9 @@ Sometimes a comment goes beyond just useful information about the implementation
}
return 1; // we are greater because we are the right type.
}
```
Here’s an even better example. You might not agree with the programmer’s solution to the problem, but at least you know what he was trying to do.
```java
public void testConcurrentAddWidgets() throws Exception {
WidgetBuilder widgetBuilder =
new WidgetBuilder(new Class[]{BoldWidget.class});
@@ -119,10 +119,10 @@ Here’s an even better example. You might not agree with the programmer’s sol
}
assertEquals(false, failFlag.get());
}
```
Clarification
Sometimes it is just helpful to translate the meaning of some obscure argument or return value into something that’s readable. In general it is better to find a way to make that argument or return value clear in its own right; but when its part of the standard library, or in code that you cannot alter, then a helpful clarifying comment can be useful.
```java
public void testCompareTo() throws Exception
{
WikiPagePath a = PathParser.parse("PageA");
@@ -142,14 +142,14 @@ Sometimes it is just helpful to translate the meaning of some obscure argument o
assertTrue(ab.compareTo(aa) == 1); // ab > aa
assertTrue(bb.compareTo(ba) == 1); // bb > ba
}
```
There is a substantial risk, of course, that a clarifying comment is incorrect. Go through the previous example and see how difficult it is to verify that they are correct. This explains both why the clarification is necessary and why it’s risky. So before writing comments like this, take care that there is no better way, and then take even more care that they are accurate.
Warning of Consequences
Sometimes it is useful to warn other programmers about certain consequences. For example, here is a comment that explains why a particular test case is turned off:
Image
```java
// Don't run unless you
// have some time to kill.
public void _testWithReallyBigFile()
@@ -162,11 +162,11 @@ Image
assertSubString("Content-Length: 1000000000", responseString);
assertTrue(bytesSent > 1000000000);
}
```
Nowadays, of course, we’d turn off the test case by using the @Ignore attribute with an appropriate explanatory string. @Ignore(”Takes too long to run”). But back in the days before JUnit 4, putting an underscore in front of the method name was a common convention. The comment, while flippant, makes the point pretty well.
Here’s another, more poignant example:
```java
public static
SimpleDateFormat makeStandardHttpDateFormat()
{
@@ -176,33 +176,33 @@ Here’s another, more poignant example:
df.setTimeZone(TimeZone.getTimeZone(”GMT”));
return df;
}
```
You might complain that there are better ways to solve this problem. I might agree with you. But the comment, as given here, is perfectly reasonable. It will prevent some overly eager programmer from using a static initializer in the name of efficiency.
TODO Comments
It is sometimes reasonable to leave “To do” notes in the form of //TODO comments. In the following case, the TODO comment explains why the function has a degenerate implementation and what that function’s future should be.
```java
//TODO-MdM these are not needed
// We expect this to go away when we do the checkout model
protected VersionInfo makeVersion() throws Exception
{
return null;
}
```
TODOs are jobs that the programmer thinks should be done, but for some reason can’t do at the moment. It might be a reminder to delete a deprecated feature or a plea for someone else to look at a problem. It might be a request for someone else to think of a better name or a reminder to make a change that is dependent on a planned event. Whatever else a TODO might be, it is not an excuse to leave bad code in the system.
Nowadays, most good IDEs provide special gestures and features to locate all the TODO comments, so it’s not likely that they will get lost. Still, you don’t want your code to be littered with TODOs. So scan through them regularly and eliminate the ones you can.
Amplification
A comment may be used to amplify the importance of something that may otherwise seem inconsequential.
```java
String listItemContent = match.group(3).trim();
// the trim is real important. It removes the starting
// spaces that could cause the item to be recognized
// as another list.
new ListItemWidget(this, listItemContent, this.level + 1);
return buildList(text.substring(match.end()));
```
Javadocs in Public APIs
There is nothing quite so helpful and satisfying as a well-described public API. The java-docs for the standard Java library are a case in point. It would be difficult, at best, to write Java programs without them.
@@ -215,7 +215,7 @@ Mumbling
Plopping in a comment just because you feel you should or because the process requires it, is a hack. If you decide to write a comment, then spend the time necessary to make sure it is the best comment you can write.
Here, for example, is a case I found in FitNesse, where a comment might indeed have been useful. But the author was in a hurry or just not paying much attention. His mumbling left behind an enigma:
```java
public void loadProperties()
{
try
@@ -231,7 +231,7 @@ Here, for example, is a case I found in FitNesse, where a comment might indeed h
// No properties files means all defaults are loaded
}
}
```
What does that comment in the catch block mean? Clearly it meant something to the author, but the meaning does not come through all that well. Apparently, if we get an IOException, it means that there was no properties file; and in that case all the defaults are loaded. But who loads all the defaults? Were they loaded before the call to loadProperties.load? Or did loadProperties.load catch the exception, load the defaults, and then pass the exception on for us to ignore? Or did loadProperties.load load all the defaults before attempting to load the file? Was the author trying to comfort himself about the fact that he was leaving the catch block empty? Or—and this is the scary possibility—was the author trying to tell himself to come back here later and write the code that would load the defaults?
Our only recourse is to examine the code in other parts of the system to find out what’s going on. Any comment that forces you to look in another module for the meaning of that comment has failed to communicate to you and is not worth the bits it consumes.
@@ -241,7 +241,7 @@ Listing 4-1 shows a simple function with a header comment that is completely red
Listing 4-1 waitForClose
```java
// Utility method that returns when this.closed
is true. Throws an exception
// if the timeout is reached.
@@ -255,14 +255,14 @@ Listing 4-1 waitForClose
throw new Exception("MockResponseSender could not be closed");
}
}
```
What purpose does this comment serve? It’s certainly not more informative than the code. It does not justify the code, or provide intent or rationale. It is not easier to read than the code. Indeed, it is less precise than the code and entices the reader to accept that lack of precision in lieu of true understanding. It is rather like a gladhanding used-car salesman assuring you that you don’t need to look under the hood.
Now consider the legion of useless and redundant javadocs in Listing 4-2 taken from Tomcat. These comments serve only to clutter and obscure the code. They serve no documentary purpose at all. To make matters worse, I only showed you the first few. There are many more in this module.
Listing 4-2 ContainerBase.java (Tomcat)
```java
public abstract class ContainerBase
implements Container, Lifecycle, Pipeline,
MBeanRegistration, Serializable {
@@ -355,7 +355,7 @@ Listing 4-2 ContainerBase.java (Tomcat)
* is associated.
*/
protected DirContext resources = null;
```
Misleading Comments
Sometimes, with all the best intentions, a programmer makes a statement in his comments that isn’t precise enough to be accurate. Consider for another moment the badly redundant but also subtly misleading comment we saw in Listing 4-1.
@@ -370,7 +370,7 @@ For example, required javadocs for every function lead to abominations such as L
Listing 4-3
```java
/**
*
* @param title The title of the CD
@@ -387,10 +387,10 @@ Listing 4-3
cd.duration = duration;
cdList.add(cd);
}
```
Journal Comments
Sometimes people add a comment to the start of a module every time they edit it. These comments accumulate as a kind of journal, or log, of every change that has ever been made. I have seen some modules with dozens of pages of these run-on journal entries.
```java
* Changes (from 11-Oct-2001)
* --------------------------
* 11-Oct-2001 : Re-organised the class and moved it to new package
@@ -410,25 +410,25 @@ Sometimes people add a comment to the start of a module every time they edit it.
* 29-May-2003 : Fixed bug in addMonths method (DG);
* 04-Sep-2003 : Implemented Comparable. Updated the isInRange javadocs (DG);
* 05-Jan-2005 : Fixed bug in addYears() method (1096282) (DG);
```
Long ago there was a good reason to create and maintain these log entries at the start of every module. We didn’t have source code control systems that did it for us. Nowadays, however, these long journals are just more clutter to obfuscate the module. They should be completely removed.
Noise Comments
Sometimes you see comments that are nothing but noise. They restate the obvious and provide no new information.
```java
/**
* Default constructor.
*/
protected AnnualDateRule() {
}
```
No, really? Or how about this:
```java
/** The day of the month. */
private int dayOfMonth;
```
And then there’s this paragon of redundancy:
```java
/**
* Returns the day of the month.
*
@@ -437,7 +437,7 @@ And then there’s this paragon of redundancy:
public int getDayOfMonth() {
return dayOfMonth;
}
```
These comments are so noisy that we learn to ignore them. As we read through code, our eyes simply skip over them. Eventually the comments begin to lie as the code around them changes.
The first comment in Listing 4-4 seems appropriate.2 It explains why the catch block is being ignored. But the second comment is pure noise. Apparently the programmer was just so frustrated with writing try/catch blocks in this function that he needed to vent.
@@ -446,7 +446,7 @@ The first comment in Listing 4-4 seems appropriate.2 It explains why the catch b
Listing 4-4 startSending
```java
private void startSending()
{
try
@@ -470,12 +470,12 @@ Listing 4-4 startSending
}
}
}
```
Rather than venting in a worthless and noisy comment, the programmer should have recognized that his frustration could be resolved by improving the structure of his code. He should have redirected his energy to extracting that last try/catch block into a separate function, as shown in Listing 4-5.
Listing 4-5 startSending (refactored)
```java
private void startSending()
{
try
@@ -503,12 +503,12 @@ Listing 4-5 startSending (refactored)
{
}
}
```
Replace the temptation to create noise with the determination to clean your code. You’ll find it makes you a better and happier programmer.
Scary Noise
Javadocs can also be noisy. What purpose do the following Javadocs (from a well-known open-source library) serve? Answer: nothing. They are just redundant noisy comments written out of some misplaced desire to provide documentation.
```java
/** The name. */
private String name;
@@ -520,29 +520,29 @@ Javadocs can also be noisy. What purpose do the following Javadocs (from a well-
/** The version. */
private String info;
```
Read these comments again more carefully. Do you see the cut-paste error? If authors aren’t paying attention when comments are written (or pasted), why should readers be expected to profit from them?
Don’t Use a Comment When You Can Use a Function or a Variable
Consider the following stretch of code:
```java
// does the module from the global list <mod> depend on the
// subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))
```
This could be rephrased without the comment as
```java
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))
```
The author of the original code may have written the comment first (unlikely) and then written the code to fulfill the comment. However, the author should then have refactored the code, as I did, so that the comment could be removed.
Position Markers
Sometimes programmers like to mark a particular position in a source file. For example, I recently found this in a program I was looking through:
```java
// Actions //////////////////////////////////
```
There are rare times when it makes sense to gather certain functions together beneath a banner like this. But in general they are clutter that should be eliminated—especially the noisy train of slashes at the end.
Think of it this way. A banner is startling and obvious if you don’t see banners very often. So use them very sparingly, and only when the benefit is significant. If you overuse banners, they’ll fall into the background noise and be ignored.
@@ -552,7 +552,7 @@ Sometimes programmers will put special comments on closing braces, as in Listing
Listing 4-6 wc.java
```java
public class wc {
public static void main(String[] args) {
BufferedReader in = new BufferedReader(new InputStreamReader(System.in));
@@ -576,7 +576,7 @@ Listing 4-6 wc.java
} //catch
} //main
}
```
Attributions and Bylines
/* Added by Rick */
@@ -586,17 +586,17 @@ Again, the source code control system is a better place for this kind of informa
Commented-Out Code
Few practices are as odious as commenting-out code. Don’t do this!
```java
InputStreamResponse response = new InputStreamResponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
// InputStream resultsStream = formatter.getResultStream();
// StreamReader reader = new StreamReader(resultsStream);
// response.setContent(reader.read(formatter.getByteCount()));
```
Others who see that commented-out code won’t have the courage to delete it. They’ll think it is there for a reason and is too important to delete. So commented-out code gathers like dregs at the bottom of a bad bottle of wine.
Consider this from apache commons:
```java
this.bytePos = writeBytes(pngIdBytes, 0);
//hdrPos = bytePos;
writeHeader();
@@ -611,14 +611,14 @@ Consider this from apache commons:
this.pngBytes = null;
}
return this.pngBytes;
```
Why are those two lines of code commented? Are they important? Were they left as reminders for some imminent change? Or are they just cruft that someone commented-out years ago and has simply not bothered to clean up.
There was a time, back in the sixties, when commenting-out code might have been useful. But we’ve had good source code control systems for a very long time now. Those systems will remember the code for us. We don’t have to comment it out any more. Just delete the code. We won’t lose it. Promise.
HTML Comments
HTML in source code comments is an abomination, as you can tell by reading the code below. It makes the comments hard to read in the one place where they should be easy to read—the editor/IDE. If comments are going to be extracted by some tool (like Javadoc) to appear in a Web page, then it should be the responsibility of that tool, and not the programmer, to adorn the comments with appropriate HTML.
```java
/**
* Task to run fit tests.
* This task runs fitnesse tests and publishes the results.
@@ -640,10 +640,10 @@ HTML in source code comments is an abomination, as you can tell by reading the c
* classpathref=&quot;classpath&quot; /&gt;
* </pre>
*/
```
Nonlocal Information
If you must write a comment, then make sure it describes the code it appears near. Don’t offer systemwide information in the context of a local comment. Consider, for example, the javadoc comment below. Aside from the fact that it is horribly redundant, it also offers information about the default port. And yet the function has absolutely no control over what that default is. The comment is not describing the function, but some other, far distant part of the system. Of course there is no guarantee that this comment will be changed when the code containing the default is changed.
```java
/**
* Port on which fitnesse would run. Defaults to 8082.
*
@@ -653,10 +653,10 @@ If you must write a comment, then make sure it describes the code it appears nea
{
this.fitnessePort = fitnessePort;
}
```
Too Much Information
Don’t put interesting historical discussions or irrelevant descriptions of details into your comments. The comment below was extracted from a module designed to test that a function could encode and decode base64. Other than the RFC number, someone reading this code has no need for the arcane information contained in the comment.
```java
/*
RFC 2045 - Multipurpose Internet Mail Extensions (MIME)
Part One: Format of Internet Message Bodies
@@ -672,18 +672,18 @@ Don’t put interesting historical discussions or irrelevant descriptions of det
the first 8-bit byte, and the eighth bit will be the low-order bit in
the first 8-bit byte, and so on.
*/
```
Inobvious Connection
The connection between a comment and the code it describes should be obvious. If you are going to the trouble to write a comment, then at least you’d like the reader to be able to look at the comment and the code and understand what the comment is talking about.
Consider, for example, this comment drawn from apache commons:
```java
/*
* start with an array that is big enough to hold all the pixels
* (plus filter bytes), and an extra 200 bytes for header info
*/
this.pngBytes = new byte[((this.width + 1) * this.height * 3) + 200];
```
What is a filter byte? Does it relate to the +1? Or to the *3? Both? Is a pixel a byte? Why 200? 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.
Function Headers
@@ -699,7 +699,7 @@ What I find fascinating about this module is that there was a time when many of
Listing 4-7 GeneratePrimes.java
```java
/**
* This class Generates prime numbers up to a user specified
* maximum. The algorithm used is the Sieve of Eratosthenes.
@@ -774,12 +774,12 @@ Listing 4-7 GeneratePrimes.java
return new int[0]; // return null array if bad input.
}
}
```
In Listing 4-8 you can see a refactored version of the same module. Note that the use of comments is significantly restrained. There are just two comments in the whole module. Both comments are explanatory in nature.
Listing 4-8 PrimeGenerator.java (refactored)
```java
/**
* This class Generates prime numbers up to a user specified
* maximum. The algorithm used is the Sieve of Eratosthenes.
@@ -863,7 +863,7 @@ Listing 4-8 PrimeGenerator.java (refactored)
return count;
}
}
```
It is easy to argue that the first comment is redundant because it reads very much like the generatePrimes function itself. Still, I think the comment serves to ease the reader into the algorithm, so I’m inclined to leave it.
The second argument is almost certainly necessary. It explains the rationale behind the use of the square root as the loop limit. I could find no simple variable name, nor any different coding structure that made this point clear. On the other hand, the use of the square root might be a conceit. Am I really saving that much time by limiting the iteration to the square root? Could the calculation of the square root take more time than I’m saving?