Names like i, j, iter, and it are commonly used as indices and loop iterators. Even though these names are generic, they’re understood to mean “I am an iterator.” (In fact, if you used one of these names for some other purpose, it would be confusing—so don’t do that!)
But sometimes there are better iterator names than i, j, and k. For instance, the following loops find which users belong to which clubs: (查看原文)
The Fundamental Theorem of Readability：Code should be written to minimize the time it would take for someone else to understand it. Remember, when in doubt, the Fundamental Theorem of Readability trumps any other rule or principle in this book. (查看原文)
1. use specific words
2. avoid generic names, like tmp and retval
3. use concrete names
4. attach important details
5. use longer names for larger scopes. use word completion.
6. use capitalization, underscores and so on in a meaningful way. (查看原文)
Part of “packing information into names” is choosing words that are very specific and avoiding “empty” words.
For example, the word “get” is very unspecific, as in this example:
def GetPage(url) The word “get” doesn’t really say much (查看原文)
What not to comment:
• Facts that can be quickly derived from the code itself.
• “Crutch comments” that make up for bad code (such as a bad function name)—fix the
code instead.
Thoughts you should be recording include:
• Insights about why code is one way and not another (“director commentary”).
• Flaws in your code, by using markers like TODO: or XXX:.
• The “story” for how a constant got its value.
Put yourself in the reader’s shoes:
• Anticipate which parts of your code will make readers say “Huh?” and comment those.
• Document any surprising behavior an average reader wouldn’t expect.
• Use “big picture” comments at the file/class level to explain how all the pieces fit together.
• Summarize blocks of code with comments so that the reader doesn’t get lost in the details. (查看原文)
This way, if == is accidentally written as =, the expression if (NULL = obj) won’t even compile.
Unfortunately, switching the order makes the code a bit unnatural to read. (As Yoda would say, “Not
if anything to say about it I have.”) Thankfully, modern compilers warn against code like if (obj =
NULL), so “Yoda Notation” is becoming a thing of the past. (查看原文)
Engineering is all about breaking down big problems into smaller ones and putting the
solutions for those problems back together. Applying this principle to code makes it more
robust and easier to read. (查看原文)
