狠狠撸

The Art of Readable Code

?? ??
The Art of Readable Code ...................................................................................................................... 1
Chapter 1. Code Should Be Easy to Understand ................................................................................... 2
Part I. Surface-Level Improvements ....................................................................................................... 4
Chapter 2. Packing Information into Names ........................................................................................... 4
Chapter 3. Names That Can’t Be Misconstrued ..................................................................................... 9
Chapter 4. Aesthetics (????? ???).......................................................................................... 12
Chapter 5. Knowing What to Comment ................................................................................................ 20
Chapter 6. Making Comments Precise and Compact ........................................................................... 27

Chapter 1. Code Should Be Easy to Understand

? ? ??? ??? ??. ?? ?? compact ?? ??, ?? ? ???? ??. ??? ?? ??? ??
??? ?? ??? ?? ??. ??? ? ???? ??? ?? ??? ? ? ??.

Code should be written to minimize the time it would take for someone else to understand it.

?? ?? ??? ?? ???? ???? ??? ??? ??? ? ??. ???? ??? ??? ? ??
? ??? ?? ???? ?? ??? ?? ?? ?? ?? ????? ?? ??? ?? ?? ??? ??
??? ??? ????, ?? ?? ?? ??? ???? ???? ?? ?????. ???? ?? ??
?? ??, ? ??? ?? ??? ?? ??? ???? ???. ????, ??? ??? ?? ??? ?
? ??.
?? ?? ?? ??? ??? ?? ????, ??? ???? ?? ??? ?? ?? ???. ?? ???
? ?? ??? ?? ?? ??? ?????, ?? ??? ?? ?? ??? ???? ??? ?? ??
?? ???.
??? ??? ?? ? ???? ?? ????? ??? ??? ??. ??? ?? ?? ???? ???
? ??? ??? ??? ? ? ??? ?? ??? ??? ??.
??? ???? ?? ??? ????.
assert((!(bucket = FindBucket(key))) || !bucket->IsOccupied());
? ??? ?? ????? ???? ????? ???? ?? ??? ?? ?????
bucket = FindBucket(key);
if (bucket != NULL) assert(!bucket->IsOccupied());
?? ?? ??? ????? ???. ?? ??? ??? ?? ??? 3? ???? ??? ???? 3?
???? ??? ??? ? ?? ?????. ????, ??? ? ?????. ??? ??? ?? ???

? ? ????.
"So even though having fewer lines of code is a good goal, minimizing the time-till-understanding is an even
better goal."
?? ??? ? ??? ?? ?? ???? ??? readable? ??? ???? ?? ????? ??? ?
? ???? ????. ???? ??? ??? ?? ??? ? ? ????. ??? ???? ?? ?? ?
? ??? ???, ??? ?????. ??? ??? ??? ????? ??? ?? ?? ? ????? ?
?? ?? ?? ??? ??? ??? ?? ?? ??? ???? ???.
?? ???? ???? ?? ???? ?? ??? ??? ?? ?? ?? ??? ???? ? ?? ???
?? ?? ??? ??? ??? ???? ???? ????. ?? ??? ? ?? ?? ????. ?? ?
? ?? ??? ??? ?? ?????. ??? ??? ?? ? ???? ??? ????? ?? ???
??? ? ????, ?? ?? ?? ????? ??? ??? ? ?? ??? ? ? ???. ??? ? ?
? ??? ?? ?? ??? ? ??? ??? ??? ??? ?? ?? ?? ??? ?? ????. ??
?, ?? ??? ?? ?? ????? ? ? ????.

Part I. Surface-Level Improvements
?? ?? ??? ? ?? ?? ?? ??, ??? ? ??, ??? ??? ???? ??? ???? ??
??? ?? ???? ???? ??? ?? ???? ??? ???. ??? ???? refactoring?? ??
?? ?? ??? ??? ??? ? ? ?? ?????, ??? ??? ?? ????. ?? ??? ??
?? ?? ?? ???? ?? ?? ? ?? ? ????. ?? ? ?? ? ??? ??? ?? ? ?? ?
???. ??? ?? ????? ??? ???, ??? ??? ??? ???.

Chapter 2. Packing Information into Names
?? ??? ?? ?? ?? ?? comment ???. ?, ???? ??? ??? ????, ? ??? ??
?? comment? ?? ?? ??? ????. ?? ??? ? ? ?????

??? 1. Choosing Specific Words.
????, ?? ?? ??? ?? ????, ???? ??? ????? ?????. ?? ??? ???
??? ?? ??? ???, ??? ????? ??? ??? ? ??? ? ?? ????. ?? ?? ??
? ??? ??? ??? ?? ?? ??? ?? ??? ?? ????.
BinaryTree.Size();
??? Size?? ?? ??? ? ???? ?? ?????. ?? ????? ?? ??? ?? ?????.
?? ??, tree? depth? ? ?? ??, node ??? ? ?? ??, ??? ??? ? ?? ???. ???
??? ??? ???? ??? ?? ???, ??? ??? ?? ?? ?? ?? ? ? ?? ????.
?? ???? ??? BinaryTree.getHeigh() ?? ???, BinaryTree.getNumNodes()?? ???? ???
?? ?? ?? ??? ??? ?? ???? ?? ? ????.

??? 2. Finding More “Colorful” Words.
?? ???? ???? ? ?? ???? ????. ??? ???? ??? ?? ??? ?? ??? ?
?? ??? ??? ????? ?????. ?? make?? ??? ?? ???? ? ? ?? ??? ??
? ??? ?? ??? ??? ??? ?????.
create, set up, build, generate, compose, add, new
??? ??? ?? ? ? ??? ??? ???, ?? ??? ?? ?? ???? ???. ??? ?? ?
?? ??? ?? ??? ? ? ??? ?? ??? ?????.

??? 3. Avoid Generic Names Like tmp and retval
????? ?? ??? ?? ??? ???? ?? ??? ????. ?? ??? tmp, retval? ??. ??

? ??? ??? ?? ??? ?? ??? ????. ??? ?? ?? ????? ????? ????
??? ?? ??? ?? ? ????.
if (right < left) {
tmp = right;
right = left;
left = tmp;
}
??? ?? ?? ?? ??? ??????
String tmp = user.name();
tmp += " " + user.phone_number();
tmp += " " + user.email();
...
template.set("user_info", tmp);
? ???? tmp? ???? ?? user_info ???? ??? ?? ???? tmp ?? userInfo?? ???
? ???? ?? ? ??? ????. ?? ? ???? ??? ??? ?? ??, ?? ? ?? ??? ?
??? ? ?? ?????. tmp?? ??, ??? ? ??? ?? ???? ??? ?? ??? ???, ?
? ???? ??? ?? ??? ?? ??? ? ????. ???, ?? ??? ?? ??? ?? ?? ?
?? ?? ?? useInfo?? ????, ?? ?? userInfo? ??? ?? ?? ?? ?? ???????.
??? ???? ??? ?? loop? ?? ?? ??? ???? ?? ??? ??? ????.
for (inti = 0; i<clubs.size(); i++)
for (int j = 0; j < clubs[i].members.size(); j++)
for (int k = 0; k <users.size(); k++)
if (clubs[i].members[k] == users[j])
cout<< "user[" << j << "] is in club[" <<i<< "]" <<endl;
?? ?? ?? ??????? ???i, j, k ? ?? ?? ???? ????? ???, ???? ??? ?
???? ??? ? i, j, k ? ??? ??? ?? j ?? i? ???? ?? ??? ??? ????. ???
???? ?? ???? ???? ?? ???? ????, ??? ?? ?? ??? ? ?? ? ????.
club_i, member_j, user_k
??? ??, ? ????? ???, ??? ??? ??? ??? ??? ? ?? ??? ?? ???? ?

??? ??? ??? ??? ???.
???, ?? ?? ??? ??? ???, ??? ?? ?? ? ?? ???? ??? ??? ? ? ???
?. ??? ? ? ?? ??? ??? ???? ??, ????? ??? ??? ? ?? ? ???.

??? 4. Prefer Concrete Names over Abstract Names
??? ?????, ???? ???? ??? ??? ??? ???. ?? A?? ???? ? ? ???
?? ??? ?? ??? ???? ???, ?? ??? ? ?? ???? ??? ???, ?? ???
abstract? ?????. ?? ???, DISALLOW_EVIL_CONSTRUCTOR?? ??? ??? ??? ???.
?? ???? ?? ???? ?? evil? ??????? ???? ?? ? ???? ?? ????? ??
DISALLOW_COPY_AND_ASSIGN ??? ???? ????? ?? ?? ????? ??? ???? ??
? ? ????. ??? ?? ??? abstract?? ?? concrete ?? ???? ???.
??? ??? ?? ????? ??? ???. –run_locally?? ??? ????. ?? ? ?? ??? ??
???? ???? ???? ??? ? ????. ??? ?????? ?? ???? ??? ????, ?
??? debugging ???? ???? ?? ????, ?? ??? ??? ???? ??? ????. ? ?
??? ????? ? ??? ?? ?? ?? ?? ??, ? ??? ?? ?? ????. ?? ?? ?? ?
? ?? ???? ?? ???? ? ??? ? ??? ???? ?????. ???, ?? ???? ???
?? ??? ?? ??? ??? ???, ?? ????? ??? ?? ? ???? ????. ??? ???
? ???? ??? ? ? ???? ??? ??? ??????. –run_locally ?? ??? –extra_logging?
?? ??? ????? ? ? ?????, ???? ?? ?? ?? ??? ??? ??? ? ?? ?? ?
?? ? ????.
? ?, ?? ?? ? ??? ?? ??? ??? ????, DB? local DB? ???? ???? ?? ??
???? ??? ?? ??? ?? ?? ????. ?? ?? ??? ???? ??? ?? ?? ??? ?
???? ???? ??? ???? ???. –user_local_database?? ?? ??? ??? ? ???. ??
? ?? ???? ??? ???? ?? ? ????. ??? ?? ???? ?? ??? ???? ???
?? ??? ????.

??? 5. Attaching Extra Information to a Name
?? ??? ?? ???? ???? ????, ???? ??? ????? ???? ???. ? ??? ?
?? ??? ?? ???? ??? ??? ?? ? ??? ???. ?? ??? ??? ???.
private String id; // hexadecimal format. For example, “af84ef845cd8”
id?? ??? ???, ?? hexa ? ??? ?? ???? ???. ??? ???? ? ?? ? ??. ??
? ???? ???? id? ???, ?? ???? ????? ??? ?? ??? ?? hexa? ??? ?
? ?????. ?? ?? ?? ??? ?? ? ??? ?? ???? ??? ?????.
private String hex_id;

??? ?? ? ??? ??????. ??? ? ??? ???? ??? ????, ??? ?? hex? ?
????? ?? ? ? ?? ????. ?? ??? ???? ?? ????. ?? ?? ??? ??? ??
???? ?? ???? ??. ??? ???? sec ???? ms ????? ??? ????? ????
??? ????. ?? ??? ? ?? ???, ??? ?? ??? ????? ?? ??? ??? ???
? ?? ???? ??? ?? ??? ???? ??? ??, ?? ??? ???? ?????. ?? ???
???? ?? ??? ????. ?? String? ??? ??? ?? ???, ?? ??? ??? ?? ? ?
? ???. ??? ??? ??? ?? ?? ??? ????.
delay?delay_secs, size?size_mb, password ?plaintext_password, html ? html_utf8, data ?data_urlenc
??? ????. ???? ???? ?????!

??? 6. How Long Should a Name Be?
?? ??? ???? ???? ??? ?? ??? ??. ???? ??, ?? ???? ???? ???
? ??. ?? ??? newNavigationControllerWrappingViewControllerForDataSourceOfClass ?? ??? ?
?. ?? ?? ?? ??? ???? ???? ?? ?? m ??? ???? ?? ??? ?? ??? ??.
?? ??? ???? ?? ??? ?? ?? ? ??.
??? ???? ???, ???? ?? ???, ??? ???? ?????. ???? ??? ??? ??
?? ??? ??? ?? ??? ???? ????. ?? ?? ??? ??, ?? ??? ?? ? ???
???? ?? ?? ??? ?? ????, ?? ?? ?? ?? ??? ???. ?? ?? ??? ?? ?
?? ????.
if (debug) {
Map<String, int> m;
lookUpNamesNumbers(&m);
print(m);
}
?? ?? ??? m??? ???? ?? ???? ???? ????? ??? ?? ????. ??? ?
? LookUpManager.m; ??? ??? ??? ??? ???. ?? ??? ????? ???? ????
LookUpManager ????? m??? ??? ?? ??? ??? ???. ?? ???? ????? ???
? ????.
? ?? ?? ??? ?? ? ??? ?????. BEPManager?? ??? ??? ????. ??? ???
?? ??? ?? ????. BackEndProcessManager?? ?? ????? ??? ???. ?? ?? ???
??. ?? ?? ?? ??? ?? ??? ??? ??? ????. ??? ?? ??? ?? ?? ????
? ??? ??? ? ???? ???? ????? ? ? ???. ?? ?? ???? ??, ???,
readDocument?? ?? ???? readDoc?? ???? ?? ? ?? ????.

???, ??? ?? ??? ?????? ???? ?? ??????, ?? ??? ?? ??? ?? ??
????? ?? ????? ?? ?? ?? ?? ??? ??? ?? ? ????.

??? 7. Use Name Formatting to Convey Meaning
??? ??? ????? ??? ??? ???? ???? ??? ??? ? ????. ?? ??? ??
? ?? ??? ??? m_pageHeight ? ?? ‘m_’? ?? ???? ??, ? ??? ???? ??? ??
?? ???. ?? ??? ???? ?? ?? ???? ?? ?? ???? ?? ?? ?? ??? ? ?
???. ?????(_), ???? ? ?? ???? ???? ???? ?? ??? ?????. ??? ??
? ??? ??? ?? ????? ??? ??? ?? ????.
“??? ??? ???? ?? ???? ?? ???? ? ??????, ??? ??? ?? ????? ?
?? ??? ?? ??? ??? ???.”

Chapter 3. Names That Can’t Be Misconstrued
?? ??? ???? ??? ???? ???? ???? ???, ??? ??? ?? ?? ? ??? ?
?? ????? ???? ???? ?????. ??? ?? ?? ??? ?? ??? ?? ??? ???
“??? ??? ? ????”? ??? ??? ? ???. ??? ??? ?? ?? ??? ???? ?? ?
?? ???? ?? ??? ?? ?? ??? ? ??? ??? ??? ????, ?? ??? ??? ??
? ???? ?? ??? ?? ? ??? ?????.
?. Filter?? ??? ??.
Results = Database.all_objects.filter(“year <= 2011”);
?? ?? ??? ?? ?, Results? ?? ????? 2011 ??? ??? ?????? ??? 2011 ??
??? ???? ???? ?????? ?? ?? ?? ?????.
??? ??? ??? ? ? ?? ?? ?? ??? select ?? exclude? ?? ?? ??? ?? ???
??? ? ?? ????.

Prefer min and max for (Inclusive) Limits
???? ?? ??? ???? ?? ?? ?? ?? ???? ???, ?????. ?? ??? ??? ?
?? ??? ? ?, ? ?? 10? ??? ? ? ??? ????? ????? ????. ??? ?? ??
? ?? ??? ?? ??? ????.
CART_TOO_BIG_LIMIT = 10
if shopping_cart.num_items() >= CART_TOO_BIG_LIMIT:
Error(“Too many items in cart”)
??? ?? ?????? ?? ?? ??? ?? ???? ??? ????? ????, ??? ??? ?
?? ????? ?? 10? ????? ?? ??? ??? ????? ????? ??? ?? ?? ? ?
??? ??? ? ?? ????? ??? ??? ???? CART_TOO_BIG_LIMIT?? ???? ????.
? ?? ?? ?? ? ?? ??? ?? ??? ? ?? ?? ??? ???, ???? ?? ???? ??
?? ?? ?????. ?? ??? ??, ?? ??? ?? ?? ? ???, ???? ?? ??? ???.
?? ??? ?? ??? ??? ? ? ??? ? ? ?? ? ????.
MAX_ITEMS_IN_CART = 10
if shopping_cart.num_items() > MAX_ITEMS_IN_CART:
Error(“Too many items in cart”)
??? ???? ???? ???? MAX? MIN??? ?? ???? ???? ?? ???? ? ? ??
??. ?? ??? ??? ? ?? ?? ????? ? ? ????. ???, ?? ???? ??? ???
? ?? ???? ? ???? ??? ? ? ???, ? ??? ??? ???. ?? ??? ??? ?? ?

???? first, last? ?? ?? ????.
??? ?????? ?? ?? ?? ??? ?? ??? ???? ??, ??? ? ? ?? ??? ???
? ?? ???? ?? ?? ??? ????. ? ??? ????? ?? ?? ???, begin/end ????.
??? end? ???? ????? ????? exclusive ? ???? ????. ?? ???? ??? ??
??? ?? ???? ?? ???? ????.
substring(intbeginIndex, intendIndex)
? ????? end? ??? ??? ?? index? ?? ??? ???? ?????.

Naming Booleans
??? ?? ?????, ????? ???? ???? ??? ? ??? ?? Boolean ?? ?? ???
??. ?? ??? booleanread_password = true; ?? ??? ?? ?, ?? ?? ?????
?? ??? ???, ??? ??? ?? ?????? ??? ? ??, ?? ??? ???? ??? ? ?
? ????. ?? ? ?? ??????. ??? ? ??? ??? ?? ??? ??? ?? ?? ????.
???? ? ?? ???? ?? ??? ? ????. ??? ? ?? ??? ?? ??? ?? ? ???
??? ???? ?? ? ?? ????. ?? ?? ??? ??? ?? ?? ?? ?? ?????.
? ??? ?? need_password ?? user_is_authenticated?? ??? ?? ????? ???? ? ? ?
??? ????? ??? ???? ?? ?? ?????. ??? ?? ? ??? ?? ???, is, has, can
?? should? ?? ??? ?? ???? ? ? ??? ?? ??? ?????. ??? ? ?? ?? ?
?? ?? ???, ??? not ??? ?? ????? ??? ?? ?? ?? ??? ?? ?? ????.
??? ?? ?? not? ???? ??? ?? ?? ??? not?? ??? ??? ???? ???, ??
??? ??? ?? ?????. ??? ??? ?? ?????? ?? ???.
Diable_ssl = false;

use_ssl = true;

? 2? ??? ssl? ????? ????, ?? ? ? ?? ?? ??? ????? Not ??? ? ?? ?
?? ??? ????? ??? ?? ?? ??? ??? ?? ?? ? ???.

Matching Expectations of Users
??? ?? ??? ?? ???? ???? ????. ?? ???? begin, end? ?????. ??? ?
??? ??? ???? ? ??? ????? ???. ?? ?? ??? ??? ?? ??? ???? ?
? ?? ?????.
? ?????. ??. ?? get?? ???? ???? ??? ? ????. ????? get?? ???? ?
?? ??? ?? ?? ??/??? ????? ??, ???? ?? ?? ??? ??? ??? ????
??? ???. ?? ???? ??? ???? ?? getMean??? ??? ???, ? ?? ? ?? ??
? ??? ?? ??? ???? ? ? ??? 10?? ??? ??? ?????. ???, ? ??? ??

? ?? ??? ???(?) getMean? ??? ????, ?? ??? ??? ??? ??? ????. ???
?? ?? ???? ??? ?? ?? ????? ???.
?? ??? ???, size ??? ????. ??? ??????? size? ??? ????. ??? ? ??
? ?? ??? O(1)? ????? ???. ???, ?? O(n2) ??? ??? ???. ? ????? ??
??? ?? ???? ????? ? ? ????? ?? ?? ??? ?????, ???? ??? ?? ?
???? ?? ?? ??? ???? ??? ???? ??????.
??? ?? ??? ?? ???? ??? ?? ??? ???, ?? ?? ??? ??? ? ?? ???
????. ??? ??? ?? ??? ???, ?? ?? ???? ???. ??? ?? ? ? ??? ??
??? ?? ?? ??? ?? ? ?? ??? ????? ???? ? ????. ??? ?? ??? ?
? ???? ???? ?? ? ? ???? ?? ?????. ?? ??? ? ???? ??? ??? ??
? ?? ????? ??? ???, ??? ??? ???? ???? ???? ????.
????? ?? ? ? ???? ??? ??? ?? ? ???????. Is_overwrite?? Boolean ?? ?
???. Is_overwrite = true; ?? ?? ?? ??????? ??? ????? ??? overwrite?? ?? ?
?? ??? ???? ??? overwrite???. ??? ??? ????? ?? can_overwrite = false; ?? ?
?? ????? ??? ?? ?? ?????? ??? ??? ? ????. ??? is_overwrite? ?? ?
? ?????? ?? ?????, ??? ????, ? ??? ???? ??? ?? ??? ?????.
??? ??? ?? ?, ??? ??? ?? ???? ?? ????. ?? ? ??? ?? ??? ?? ?
? ?? ?? ?? ? ????.

Chapter 4. Aesthetics (????? ???)
?? ??? ???. ?? ??? ????? ??? ??? ??? ??, ?? ??? ??? ?? ???
?? ??? ???? ?? ?? ??? ???? ???? ??? ?? ????. ?? ??? ?? ??
??? ????? ?? ???? ??? ?? ?? ??? ???. ??? ??? ???? ??? ??
? ?????. ?? ? ???? ??? ????? ?? ?? ??? ?? ???.

????? ?? ????? ?? ??? ????, ??? ?? ?? ????.

?? ?? ?? ?? ??? ??? ??? ??? ?? ???? ??? ?? ??? ??? ??? ??
? ???? ?????. ??? ?? ??? ???? ?? ?? ?? ??? ?? ???? ? ? ??
???? ?? ??? ???.

Rearrange Line Breaks to Be Consistent and Compact
?? ??? 80? ??? ??? ?????, ???? ??? ????? ???. ??? ? ??? ??
? ? ? ??? ?? ? ? ???? ?? ??? ?????. ?? ??? ?????.

? ?? ????? ?? ? ?? ???? ?? ??? ???? ?? ?? ??? ?? ?? ???? ??
???? ?? ?????. ? ??? ????? ??? ?? ?????.

??? ?? ? ?? “??? ??? ?? ??? ??? ??? ???? ??.”?? ??? ?? ???
??? ??? ? ????. ? ?? ???, ? ? ????? ???? ?? ?? ???? ?? ?? ??
?? ??? ?? ???? ? ????. ?? ???? ?? ??? ??? ? ???.

??? ??? ? ??? ???, ?? ???? ??? ???? ??? ??? ???? ??? ????.
?? ??? ???? ? ? ? ???? ???? ??? ?? ??? ??? ??? ?? ???? ?? ?
?? ?? ??? ??? ????. ??? ??? ??? ??? ???? ???? ??? ?? ???
??? ??????.

Use Methods to Clean Up Irregularity
???? ???? ??? ???? ????. ???? ??? ??? ??? ?? ??? ??? ?? ?
?? ? ???? ??? ??? ??? ???? ??? ???????. ?? ?? ?????. ^^

? ??? ExpandFullName? ??? ??? ?? ?????. ?? ??? ????? ??? ?? ??
???? ??? ?? ????. ExpandFullName(database_connection, …) ?? ??? ??? ???. ?
??? ?? ??? ??? ???? ??? ??? ??? ???? ??? ??? ??? ???? ??
?. ? ??? ??? ??? ???? ?? ???. ?? ? ??? ??? ??? ??? ?? ?????.

?? ????? ????? ?? CheckFullName? ????? ??? ??? ???? ?? ?????
? ?????, ?? ??? ???? ?? ?? ?? ????? ??? ????? ??? ? ????.

?? ?? refactoring?? ??? ?? ? ????? ???. ?? ???? ?? ???? ??? ???
??? ???? ????? ???. ?? ??? ??? ????.

??? ??? ???, ??? ??? ?? ?? ??? ?? ??? ???? ?? ???, ???? ? ?
??? ???? ?? ??? ??? ??? ? ? ????. ?? ??? ?? ??? ????? ? ?
?? ???? ??? ???? ? ? ????.

Use Column Alignment When Helpful
?? ? ??? ??? ???? ???? ??? ? ????, ?? ? ? ?????. ?? ??? ???
? ?? ??? ??? ????, column ??? ?? ?? ??? ?????. ?? ??? ?? ????
? ??? ?????.

?? ???? ???? ? ???? ?????? ??? ??? ? ?? ????. ??? ??? ???
?? ?? ?? ?? ?? ???? ????? ?? ??? ?? ??? ??? ? ?????.

????? ? ?? ????? ???? ???? ?? ?? ??? ?? ?? ????? ? ?? ? ??
???? ??? ??? ???? ?? ??? ????. ?? ? ????? ???? ??? ??? ??
? ???? ??? ???. ?? ?? ??? ???.

? ?? ????? ?? ?? ?? ????? ? ? ?? ?? ???? ? ?????. ??? ? ???
??? ????. ?? ?? ??? ?? ????? ? ?????, ??? ?? ??? ???. ? ???
?? ??? ???? ?????? ?? ? ?? ??? ??? ??? ?? ??? ??? ?????.

?? ?????? Phone? ?? ????? request? r? ?? ??? ??? ???? ??? ??? ??
?? ?? ?? ? ?? ??? ??? ???, ?? ?? ?? ??? ??? ???.
? ?? ?? ??? ???? ?? ??? ? ???. ??? ????, diff ?? ???? ?? ??? ?
?? ???. ??? ??? ?? ? ?????. ?? ?? ??? ???. ????, diff ???? ???
???? ?? ?? ???? ????. ??? ??? ??? ?? ?? ??? ??? ????. ? ? ?
?? ?? ?? ????. ??? ??? ? ?? ?????.

Pick a Meaningful Order, and Use It Consistently
???? ?? ??? ??? ?? ??? ?? ?????. ??? ?? ??? ???? ??? ????
????. ?? ??? request.POST.get? ??? ?? ???? ??? ?????. ? ??? ????
? ??? ?????.

? ??? ??? ??? ?? ??? ?? ??? ??????.

??? ??? ?? ??? ?? ???? ????? ?? ????? ?????. ???? ??? ???
???? ???? ????? ????. ???, ?? ?? ??? ??? ??? ??, ??? ?? ??
??? ? ?? ???. ??? ?? ??? ??? ???? ???. ?? ?? ???? ??? ? ???
?? ?? ?? ?? ??? ?? ? ????.

Organize Declarations into Blocks
?? ??? ?? ??? ???? ? ??? ????? ?? ??? ?????, ?? ???? ? ? ?
? ?????. ?? ??? ???.

? ??? ?? ????? ?? ?? ???? ??? ???? ???? ??? ? ? ???, ?? ??
? ?????. ? ? ??? ??????. ? ? ??? ??? ??? ???? ??? ??? ????
???? ??? ????.

???? ?? ???? ??? ?? ??? ???? ?? ??? ???? ???? ???, ?? ???
?? ?? ??? ?? ?? ?? ????. ??? ??? ??? ? ?? ?? ? ? ??? ???, ??
?? ? ?? ?? ?? ?? ????. ???? ??? ?? ??? ??? ????, ?? ??????
??? ??? ??? ??? ???? ????? ?? ??? ???, ??? ?? ?? ???? ???
???? ???.

Break Code into “Paragraphs”
? ??? ?? ??? ???? ?? ?? ????, ??? ?? ?? ???? ??? ???? ?? ?
?? ?? ? ???, ?? ??? ???. ?? ???? ?? ?? ?? ?? ?? ?? ?? ?? ???
???.

? ??????! ??? ??? ?? ??? ? ????.

?? ??? ????, ?? ???? ????. ?? ???? ? ??? ??? ??? ?? ?? ? ??
‘?? ??~’ ??? ‘? ????.’ ??? ??????.

Summary
???? ? ??? ?? ???? ?? ??? ???. ??? ??? ??? ?? ??? coding
convention? ??? ??? ??? ???, ??? ?? ??? ?? ????? ??? ?? ?? ???
? ????. ??? ? ?? ???? ?? ??? ?? ?????.

??? ??? ?? ??? ????, ?????. ??? ? ??? ??? ??? ??? ??? ????
???. ?? ?? ??? ??? ????.

Chapter 5. Knowing What to Comment
??? ??? ?? ?? ????. ???, “? ??? ??? ???”? ??? ??? ? ? ?
? ??? ????. ?? ?? ?? ?? ?? ??? ??? ??? ?? ?? ? ??? ??
?????. ?? ?? ??? ????, ?? ??? ??? ?? ??? ?? ??? ?? ??
???.
??? ???? ??? ???? ??? ???? ??? ?? ???? ?? ??? ??? ?
? ??? ???? ?????. ??? ??? ?? ?? ??? ? ?? ????. ??? ??
???? ?? ????? ? ??? ?? ?? ??? ??? ?? ??, ?? ?? ??? ?
????? ???? ??? ? ?? ????? ??? ??? ????. ??? ???? ??
? ???? ??? ??? ??? ???? ???.
Knowing what not to comment
?? ??? ??? ?? ? ?? ?????. ??? ??? ???? ?? ?? ? ?? ??
???. ???? ??? ?? ??? ???? ?? ??? ??? ??? ??? ? ? ???.
?? ???? ?? ??? ???.

? ??? ?? ??? ?????? ?????? ???? ????. ?? ??? ???? ??
?? ?? ??? ?? ?? ?????. ??? ??? ??? ?? ??? ?? ?????.
?? ???? ?? ? ? ?? ??? ???? ??? ?? ???.
??? “?? ? ? ??” ??? ?? ?????? ?? ??? ?? ???? ???? ??
??? ???.

? ??? ????? ? ??? ??? ?? ?? ?? ?? ???? ??? ????. ???
?, ??? ??? ???? ??? ??? ?? ???? ?? ? ????. ?? ??? “??

? ? ??”??? ???? ? ??? ??? ?? ????. ? ??? ?? ???? ? ? ?
? ?? ???? ????, ??? ?????, ??? ??? ?? ?? ???? ??? ??
? ???? ? ? ???.
? ? ??? ??? ??? ????, ??? ??? ?? ?? ?? ??? ??? ??? ?
???? ???? ???, ? ???? ??? ?? ??? ?? ??? ????.

??? ?? ?? ?? ?? ?????. ? ??? ?? ??? ??? ??? ??? ?? ?
??. ??? ??? ???? ???? ?? ????? ???. ?? ? ?? getter/setter? ?
? ?? ?? ???? ?????. ?? ??? ??? ?? ?????? ???? ??? ?
??, ??? ?? ????? ??? ?? ?? ???? ???? ??? ????? ???
??? ???.

?? ? ??? ? ??? ???. ?? ?? ???? ?? ? ?? ??? ?? ???? ??
? ??? ??? ?? ?????. ?? ?? ??? ??? ???.
??? ??? ??? ?? ??? ????.

????? ?? ??? ??? ?? ????? ?? ?????? ?? ?? ??? ?? ???
?? ??? ??? ?? ??? ?? ???? ???. ?? ???? ?? ? ??? ????
?? ? ??? ??? ?? ??? ?????.

?? ?????? ?? ?? ??? ? ? ???, ??? ???? ??? ???? ????
???? ????. ??? ?? ?? ?? ??? ??? ???? ???, ?? ?? ????
?? ? ?????. ? ?? ??? ?????.
??? ???? ????? ???? ???? ???? ????. ? ? ??? ???? ??

???? ?????, ??? ???? ?? ??? ?? ?? ??? ??? ???? ???
?? ?? ??? ??? ???? ???? ?? ????. ??? ?? ??? ?? ????
??? ?? ??? ???? ????. ??? ?? ?? “?? ???? ????.”?? ??
???? “??? ? ? ????, ? ? ??!”?? ?? ?? ??? ?? ?? ?? ?? ??
??????. ?? ? ? ?????. ?? ?? ??? ??? ???? ?? ??? ????
??? ??? ???, ???? ???? ?? ??? ???.
?. Self-documenting?? ??? ???? ???? ????. ?? ?? ??? ?? ????
???? ????? ???. ?? ???? ?? ?? ? ? ???.

? ?? ??? ??? ??? ????. ?????? ????. ??? ??? ?? ????
?? ?????? ??? ?? ?? ?? handle? ????? ???. ?? ?????? ? ?
?? ??? ??? ?? ??? ?? ?????

????? ?? ??? ?? ??? ?? ? ???? ????. ?? ??? self-documenting?
? ??? ???? ???.
Recording your thoughts
???? ??? ?? ??? ?? ??? ??? ???? ????. ??? ??? ???? ?????
?? ?? ??? ???????.
?? ???? ??? ??, ?? ??? ??? ?? ???? ??? ?? ??? ???? ?? ?? ?
????. ??? ?????? ??? ???? ?? ???? ???. ??? ??? ?? ?? ??? ?
? insight? ?? ????? ?? ????. ?????. ????? ?? ?? ??? ???.

? ??? ?? ??? ???? ?? ??? ??? ??? ? insight? ?? ??? ????? ???
?? ??? ???? ??? ?? ??? ?? ??? ? ?? ??? ??? ???? ???? ????.
?? ??? ?? ??? ?? insight ?? ?? ?????. ? ?? ?? ???.

? ??? ?????? ?? ? ??? ???, ?? ??? ?? ??? ?? ??? ???? ?? ??
?? ??? ??? ????. ???? ? ????? ???? ?? ???? ?? 100%? ???? ?

?? ?? ???? ???. ????? ??? ????. ??? ?? ?? ??? ????? ???, ?
? ??? ?? ??? ??? ??, ?? ??? ????? ?? ?? ??? ?? ? ?? ???. ??
? ?? ??(?? ?? ?? ??)? ?? ?? ???.

? ??? ?? ??? ???. ??? ?? ??? ?? ??? ??? ?? ???? ????? ?? ?
???. ? ????? ??? ? ?? ???? ???? ?? ????. ??? ??? ???? ???
??? ????? ???? ?? ???? ??? ??? ? ????. ??? ????? ?? ??? ?
? ???? ?? ?????.

? ???? ??? ? ? ??? ??? ???? ????, ??? ? ??? ??? ???? ??? ?
? ????. ??? ??? ??? ?? ??? ???? ?? ?? ??? ????. ??? ?? ???
??? ????. ?? ??? ??? ???? ??? ??? ???????. ???, ??? ??? ??
??? ????. ???? ??? ??? ??? ????. ??? ?? ?? ??? ????, ?? ??
??? ?? ??? ?? ? ???? ?? ??? ??? ???? ??? ?? ????. ?? ?? ??
?? ????? ????? ???? ?? ? ???.
??? ?? ???? ??? ?? ?? ??? ?? ?? ????? ??? ? ? ?? ??? ????.
?? ??? ?? ?????. ?? ?? ???. ?? ??? ????.

? ??? ?? ?? ??? ???? ?? ?? ?? ?? ???? ?? ??? ????, ?? ??? ?
? ?? ???? ?? ? 8?? ???. ??? ???? ????? ?? ?? ??? ??? ?? ???
? ????. ? ??? ??? ?? ?? ???, ??? ????.

?? ?? ??? ?? ???, NUM_THREADS?? ?? ?? ??? ?, ??? ?? ?? ?? ??, ?
?? ?? ?? ?? ??? ? ? ????. ??? ?? ??? ????? ? ???.

? ?? ?? ????, ?? ?? ??? ????? ??? ????? ??? ??? ??? ? ? ??

??. ? ????? ? ? ? ??? ?? ????? ??? ??? ? ?? ??? ??? ?????.
?? ?? ??? ?? ??? ??? ??? ????. ?? ??? SECONDS_PER_DAY ?? ??? ?
??, ? ?? ??? ??? ?? ?? ??? ?? ?? ????.
??? ?? ????? ? ????? ???? ?? ????. ? ??? ?? ???. ^^

Put Yourself in the Reader’s Shoes
??? ???? ?? ?? ??? ??, ?? ??? ??? ?? ?? ???? ??? ???? ???
???? ? ??? ?? ????. ?? ?? ???? ??? ??? ?? ???. ?? ?? ??? ??
? ???.

? ???? ?? ??? ??? ?? ??? ?? ???? ? clear?? swap? ??? ?? ??? ??
?? ? ??? ??? ??? ?????. ? ??? ?? ??? ?? ??? ? ?? ?? ?? ?? ?
? ??? ???, ????? ?? ?? ??? ?? ????.

??? ?? ??? ??? ??? ??? ??? ??? ??, ???? ?? ????? ?? ??? ?
?? ??? ????. ???? ??? ??? ?? ? ? ?? ? ?? ??? ??? ??? ?? ??
??. ?? ??? ?? ?????.

? ??? ? ??? ??? ?? ?? ??? ???? ?? ??? ????. ?? ?? ???? ???
??? ??? ?? ? ??? ?? ??? ??? ?? ?? ??? ??? ??? ???, ??? ???
?? ????, ? ?? ?? ?? ?? ? ??? ?? ?? ?? ? ??, ?? ???? ??? 1? ??
? timeout ?? ??? ??????. ??? ??? ??? ??? ? ??? ???.
??? ???, ?? ??? ??? ?? ?????, ??? ??? ???? ??? ??? ? ???. ?
? ???? ??? ?????? ?? ??? ? ??? ????? ????, ?? ?? ??? ????
?? ???? ???? ??? ?? ??? ?????.

??? ??? ??? ???, ?? ??? ?? ??? ???? ??? ?? ? ?? ?? ??? ???

?? ? ??? ??????. ??? ?? ??? ?? ??? ? ?? ?? ??? ?? ??? ????
?? ?? ???? ? ????.

????? ?? ?? ???? ??? ???, ?? ??? ?????. ??? ?? ??? ??? ???
???? ?? ??? big picture? ?? ??? ??? ??? ????. ??? ??? ?? ?????
???? ???? ??? ??? ?? ???? ???? ? ?, ???? ?????? ????? ??
?. ?? ??? “? ???? ?? ???? ?? ??? ??, ? ???? ???? ??? ??????
? ???? ???? ?? ?? ???? ????? ? ??? ???? ???…” ??? ????? ?
? big picture? ?? ??? ??, ??? ? ??? ??? ???? ??? ????? ???. ???
?? ??? ?? ??? ?? ? ????.

?? ??? ??? ?, ?? ? ??? ??? ??? ???. ? ??? ??? ??? ??? ? ???
?? ??????.
??? ?? ???? ?? ??? ??? ??? ???? ????. ? ??? ???, ???? ???
???? ??? ??? ? ??? ???? ?? ?? ??? ?? ???? ?? ?????. ??? ?
? ?? ?? ?? ??? ??? ? ????.

?? ?? ??? ? ?? ????. ????, ?? ??? ? ??? ??? ??? ???? ???? ?
? ??? ?? ??? ????? ? ????. ??? ?? ? ??? ???? ?????. ?? ???
????? ???? ?? ??? ?? ?????. ? ??? ???? ?? ???? ??? ?????,
??? ? ? ???? ??? ?? ??? ??? ?? ?? ?? ?????. ?? ?? ?? ?????.

???? ??? ???? ??? ??? ???????. ??? ???? ??? ?? ?? ?? ?? ?
? ????? ?? ????. ??? ??? ?? ?? ???, ?? ??? ????? ??? ??? ?
?? ?? ????? ???? ?? ????. ??? ???? ??? ??? ??? ????? ???
? ??? ???? ???? ???. ?? ??? ?? ????? ??? ?????? ??? ?? ??
??? ????. ??? ??? ??? ??? ?? ???? ????, ?? ?? ???? ??? ???
?? ???? ^^

Summary
??? ?? ?? ?? ????? ???, ?? ?? ????, ??? ???? ?? ??? ??? ??
? ?? ??? ??? ??? ????? ???? ??? ??? ????. ?? ??? ??? ????
???? ??? ????.
?

?? ?? ??? ? ?
?
?

?

?? ???? ?? ??? ?? ??
??? ?? ??? ???? ?? ??. ?? ?? ??? ??

???? ????? ? ?
?
?

??? ??? ????? ? ???? ?? ??? ??

?
?

??? ??? ??? ?? ? insight? ??

???? ?? ??? ??? ? ??

?? ? ???? ??? ?? ??? ???? ? ??
?

?? ?? ?, ?? ???? ? ??? ?? ??

?

????? ?? ??? ?? ??? ?? ??

?

???? ??? ???? ??? ??? ? ? ? ?? ??

?

?? ??? ???? ?? ??? ?? ?? ??

??? ??? ???? ?? ??? good code > bad code + good comments. ???.Good code? ????
???? ???? ?? ??? ???? ?? ??? ?? ?? ????? ??? ???? ???? ?
? ?? ??? ??? ???.

Chapter 6. Making Comments Precise and Compact
???? ?? ??? ??? ??? ???? ??? ???????. ??? ?? ??? ???? ??
?? ?? ???, ??? ?? ? ? ?? ????? ??? ????.
?? ??? ??? ??? ?? ?? ? ???? ??? ??? ???? ?? ????? ?? ???.
??? ???? ????, ???? ?? ???? ??? ??? ????. ??? ??? ??? ???
???? ?? ? ?? ????. ??? ?? ??? ?? ??? ????.
// int? CategoryType??.
// ?? pair? ??? float? score??. ??? ? ??? Weight??.
Typedefhash_map<int, pair<float, float>>ScoreMap;
???? ???? ???? ??? ?? ?? ????, ??? ?? ??? ?? ??.
// ??: CategoryType, <score, weight>
Typedefhash_map<int, pair<float, float>>ScoreMap;
??? ???? ?? ??? ? ???? ?? ?? ??. ????, ??? ?? ??? ?? ? ???.
??? ??? ?? ??? ? ? ?? ??? ?? ? ??? ?? ???? ?????. ??? ???
??? ??? ?? ?? ?? ??? ??? ???? ??? ??? ??? ?? ??? ? ? ??? ?
????.
??? ??? ???? ??? ?? ???, ??? ? ??? ??? ?? ?? ???? ???, ?? ?
?? ??? ?? ???? ???? ????. ? ? ?? ?????? ???? ??? ???? ???
?. ?? ???? ??? ?? ???? ??, ?? ??? ?? ? ?? ????? ???? ?? ???
?? ??? ???.
?

??? ??? ???
?
?

?

?? ?: ???? ??? ?? ??, ??? ??? ??? ?? ?????.
?? ?: ??????? ?? ??, ???? ?? ???? ??? ?????.

???? ????, ?? ??.
?
?

?

?? ?: ? URL? ?? ?????? ??? ?? ?? ??? ????.
?? ?: ?? ???? ?? URL? ????? ?????.

???? ??? ????? ????.

?

?? ?: ? ??? ?? ? ?? ?????.

?

?? ?: ?? ?? ? ?? ???? n ??? ??? ?????.

??? ??? ??? ?? ????, ???? ??? ???? ?? ??? ???? ?? ?? ????
?. ?? ?? ????? ?? ??? ?? ?? ?????. ???, ??? ?? ??? ???? ???
? ? ?? ? ??? ?? ??????.
?

?? ??? ?? ??? ?? ??? ?????.
?

producst.sort(CompareProductByPrice);
for(list<Product>::reverse_iterator it = products.rbegin(); it != products.rend(); ++it) {
DisplayPrice(it -> Price);
……
}

?

? ??? ???, “???? ??? ???? ???? ??? ??? ?????.”? ??
??? ??? ??? ?? ???, “??? ?? ??? ?? ? ??? ??? ???.”??
??? ?? ??? ???? ?? ????.

?

?? ???? ????? ??? ??? ?? ?????.
?

Connect(10, false, 5);

?

? ??? ??? primitive ??? ?? ?? ??? ???? ???? ?? ?? ????
??? ?? ? ???? ?? ??? ????. ? ? ??? ?? ??? ???? ? ?
???? ????. ?? ???? ?? ???? ?? ??? ????, ??? ?????.
??? ?? ?? ??? ?? ??? ?? ??? ????.

?
?

Connect( /* timeout_ms= */ 10, /* use_encryption= */ false, /* max_retry_times= */ 5);

???? ?? ??? ?? ???? ??? ??? ???? ?? ??.
?

???? ??? ?? ??? ???? ??? ???? ?? ??? ??? ? ? ????.
????, ?? ??? ??? ??? ?? ???? ??? ?? ??? ?? ??? ???
?? ?? ???? ??? ?????.

?

???? ??? ???? ??? ??? ?? ? ? ????. ^^;;
?

? ???? ??????? ??? ??? ?? ??? ??? ???, ?? ??? ?
????? ????. ??? ? ???? ???, ?? ??? ?? ????? ???
?, ?? ?? ??? ? ?? ????. ?? ??? ???????? ?? ????
???? ???, ??? ??? ? ?? ??? ?? ????.

?

??? ?? ??? “? ???? ??????? ?? ?? ???? ????.”?? ???
? ?? ??? ?????.

?

??? ?? ?????.
?

?? ??? ??? ???? ??? ??? ?? ???, ??? ?? ??? ??? ???
?? ????. ?? ?? ?? ??? ? ? ?? ???? ???? ???? ???? ?
? ????.

?

???? ??? ???? ??? ????? ???? ?? ??? ????. ?? ?? ?
?? ????.
?

“unhappy”.substring(2) = “happy”
“unhappy”.substring(7) = “”

??? ??? ???? ????, ??? ??? ?? ?? ??? ?? ??. ?? ?? ??? ?? ?
??? ??? ??? ??? ??? ???? ????? ??? ?? ??? ??? ??? ???.

狠狠撸

The Art Of Readable Code.

More Related Content

The Art Of Readable Code.