Readability and Naming Things
Link: http://www.codesimplicity.com/post/readability-and-naming-things/#more-797
很多人认为决定代码可读性的关键在于他们所使用的字母和符号。他们相信对符号的调整可以改善程序的可读性。在一定程度上，他们是正确的。然而，更基本的原则是：
代码的可读性首先由字母和符号的长度（所占空间）决定。
这将意味着：
代码中需要适当数量的字母，不多也不少。
在一行代码中需要通过空格来分离不同的部分，不同的操作应该在不同的行中出现并使用适当的缩排。
它实际上是通过空缺来使代码具备更好地可读性。这是生活的一种普遍方式，比如说，如果一本书中不含任何的空格，你将无法阅读。另一方面，在晴朗的夜晚，我们能更清楚地看到月亮，因为那里有大片的黑色背景而不是月亮。同样地，如果你的代码中有适当数量的空格，你就能够更清楚地理解代码想要做的究竟是什么。
比方说，这段代码很难阅读：
x=1+2;y=3+4;z=x+y;print"hello world";print"z is"+z;if(z>y+x){print"error";}
然而当其中有适当的空格时，代码就变得非常清晰：
x = 1 + 2;
y = 3 + 4;
z = x + y;
print "hello world";
print "z is" + z;
if (z > y + x) {
print "error";
}
然而太多的空格会成为一种累赘，也将使代码很难阅读：
x = 1+ 2;
y = 3 +4;
z = x + y;
print "hello world" ;
print "z is " + z;
if (z > y+x)
{ print "error" ;
}
代码占据的空间应该与其含义占相同的比例。
一般来说，用少量的字母来表示大量的含义经常会使代码难以阅读。而用很长的名字表示简单的含义也会使阅读代码变得困难。含义的多少应该与其所占的空间(字符串长度)成正比。
比方说，这段代码不具任何可读性应为它所使用的函数、变量名都太过简单了。
q = s(j, f, m);
p(q);
与他们的含义相比，这些名字是在是太短了。然而，通过使用长度适当的名字，能够使代码具备更强的可读性，比如：
quarterly_total = sum(january, february, march);
print(quarterly_total);
另一方面，如果这些名字与其含义相比太过复杂的话也将导致代码难以阅读，例如：
quarterly_total_for_company_x_in_2011_as_of_today = add_all_of_these_together_and_return_the_result(january_total_amount, february_total_amount, march_total_amount);
send_to_screen_and_dont_wait_for_user_to_respond(quarterly_total_for_company_x_in_2011_as_of_today);
与单独的命名法则一样，这项原则也适用于一整块的代码。我们可以通过一个简单的函数调用来取代这个代码块地功能：
print_quarterly_total();
并且，这种方式与前面的几个例子相比，具备更好的可读性。尽管这个函数名与其它的名字相比显得稍长一些，而它包含了更多的含义使我们能够欣然接受。实际上，它具备更好地可读性。这是因为，代码块通过大量的字符串表示一个简单的过程，而我们能够通过更简单的函数名来实现。
如果一个代码块占据了很多的空间而实际上却没有复杂的功能时，你最好将这个函数重构。比方说，这段代码用来处理用户的输入：
x_pressed = false;
y_pressed = false;
if (input == "x") {
print "You pressed x!";
x_pressed = true;
}
else if (input == "y") {
if (not y_pressed) {
print "You pressed y for the first time!";
y_pressed = true;
if (x_pressed) {
print "You pressed x and then y!";
}
}
}
如果这就是我们的整个程序，它已经具备了足够的可读性。然而，如果它这是一个复杂工程中的一小段代码，我们最好重构以使其具备良好的可读性：
x_pressed = false;
y_pressed = false;
if (input == "x") {
handle_x(x_pressed);
}
else if (input == "y") {
handle_y(x_pressed, y_pressed);
}
我们甚至可以通过函数的方式将其精简成这样，它就具备了足够的可读性：
handle_input(input);
在我们的工程中读到“handle_input”这样的代码，总比试图理解整个代码块的功能更容易些，因为“handle_input”占据了适当的空间，而整个代码块占据的空间太多了。然而，如果我们是h(input)来代替，它将会导致严重的歧义因为h太过简短而不足以表达一定的含义。类似地，handle_this_input_and_figure_out_if_it_is_x_or_y_and_then_do_the_right_thing(input)这样的函数名也不是一种好的选择。
命名法则
一个著名的软件工程师曾经说过，命名法则是计算机科学中最为复杂的问题。
前面关于可读性的原则为我们的命名法则提供了一定的线索。通常情况下，一个变量、函数的名字应该足以表达其完整的含义而不至于显得过于累赘。
考虑函数或者变量的实际使用也同样重要。一旦我们将这些名字放入成行的代码，它是否会导致整行的代码过长而降低其可读性。如果一个函数在整个工程中只会被调用一次，它却是可以拥有足够长的名字，而如果它将在复杂的表达式
[原文]
Many people think that the readability of code has to do with the letters and symbols used. They believe it is the adding, removing, or changing of those symbols that makes code more readable. In some sense, they’re right. However, the underlying principle is:
Readability of code depends primarily on how space is occupied by letters and symbols.
What does that mean? Well, it means two things:
Code should have the proper amount of white space around it. Not too much, not too little.
There should be the proper amount of space within a line of code to separate out the different parts. Separate actions should generally be on separate lines. Indentation should be used appropriately to group blocks of code.
With this principle, it’s actually the absence of code that makes things readable. This is a general principle of life–for example, if there was no space at all between letters and words in a book, it would be hard to read. On the other hand, it’s easy to see the moon against the clear night, because there’s a lot of clear black space that isn’t the moon. Similarly, when your code has the right amount of space in it, you can tell where and what the code is easily.
For example, this code is hard to read:
x=1+2;y=3+4;z=x+y;print"hello world";print"z is"+z;if(z>y+x){print"error";}
Whereas with the proper spacing in, around, and between the lines, it becomes easy to read:
x = 1 + 2;
y = 3 + 4;
z = x + y;
print "hello world";
print "z is" + z;
if (z > y + x) {
print "error";
}
There can also be too much or wrong space, however. This code is also hard to read:
x = 1+ 2;
y = 3 +4;
z = x + y;
print "hello world" ;
print "z is " + z;
if (z > y+x)
{ print "error" ;
}
Code itself should take up space in proportion to how much meaning it has.
Basically, tiny symbols that mean a lot make code hard to read. Very long names that don’t mean much also make code hard to read. The amount of meaning and the space taken up should be closely related to each other.
For example, this code is unreadable because the names are too small:
q = s(j, f, m);
p(q);
The space those names take up is very little compared to how much meaning they have. However, with appropriately-sized names, it becomes more apparent what that block of code is doing:
quarterly_total = sum(january, february, march);
print(quarterly_total);
On the other hand, if the names are too long compared to how much meaning they represent, then the code becomes hard to read again:
quarterly_total_for_company_x_in_2011_as_of_today = add_all_of_these_together_and_return_the_result(january_total_amount, february_total_amount, march_total_amount);
send_to_screen_and_dont_wait_for_user_to_respond(quarterly_total_for_company_x_in_2011_as_of_today);
This principle applies just as well to entire blocks of code as it does to individual names. We could replace the entire block of code above with a single function call:
print_quarterly_total();
And that is even more readable than any of the previous examples. Even though the name we used–print_quarterly_total–is a bit longer than our other names for things, that’s okay because it represents
more meaning than other pieces of code do. In fact, it’s even more readable than our block of code was, by itself. Why is that? Because the code block took up a lot of space for, effectively, very little meaning, and the function takes up
a more reasonable amount of space for the same meaning.
If a block of code takes up a lot of space but doesn’t actually have much meaning, then it’s a good candidate for refactoring. For example, here’s a block of code that handles some user input:
x_pressed = false;
y_pressed = false;
if (input == "x") {
print "You pressed x!";
x_pressed = true;
}
else if (input == "y") {
if (not y_pressed) {
print "You pressed y for the first time!";
y_pressed = true;
if (x_pressed) {
print "You pressed x and then y!";
}
}
}
If that were our whole program, that would probably be readable enough. However, if this is within a lot of other code, we could make it more readable like this:
x_pressed = false;
y_pressed = false;
if (input == "x") {
handle_x(x_pressed);
}
else if (input == "y") {
handle_y(x_pressed, y_pressed);
}
And we could make it even more readable by reducing it to this:
handle_input(input);
Reading “handle_input” in the middle of our code is much easier than trying to read that whole first block, above, because “handle_input” is taking up the right amount of space, and the block is taking up too much space. Note, however, if we’d done something
like h(input) instead, that would be confusing and unreadable because “h” is too short to properly tell us what the code is doing. Also,
handle_this_input_and_figure_out_if_it_is_x_or_y_and_then_do_the_right_thing(input) would not only be annoying for a programmer to type, but would also make for unreadable code.
Naming Things
It was once said by a famous programmer that naming things was one of the hardest problems in computer science. These principles of readability give us some good clues on how to name things, though. Basically, the name of a variable, function, etc. should be long enough to fully communicate what it is or does, without being so long that it becomes hard to read.
It’s also important to think about how the function or variable is going to be used. Once we start putting it into lines of code, will it make those lines of code too long for how much meaning they actually have? For example, if you have a function that is only called once, on one line all by itself, with no other code in that line, then it can have a fairly long name. However, a function that you’re going to use frequently in complex expressions should probably have a name that is short (though still long enough to fully communicate what it does).
-Max