Readability and Naming Things

Document directory

• Code shoshould have the proper amount of white space around it. Not too much, not too little.
• Code itself shocould take up space in proportion to how much meaning it has.
• Naming Things

Readability and Naming Things

Link:

Http://www.codesimplicity.com/post/readability-and-naming-things/#more-797

 

Many people think that the key to determining code readability is the letters and symbols they use. They believe that symbol adjustment can improve the readability of the program. To some extent, they are correct. However, the more basic principle is:

The readability of the Code is first determined by the length (space occupied) of letters and symbols.

This will mean:

The Code requires an appropriate number of letters.

In a line of code, separate different parts by spaces. Different operations should appear in different rows and use appropriate contraction.

It actually makes the code more readable through vacancies. This is a common way of life. For example, if a book does not contain any space, you will not be able to read it. On the other hand, on a clear night, we can see the moon more clearly, because there is a large black background rather than the moon. Similarly, if your code contains a proper number of spaces, you can better understand what the code is.

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 ";}

 

However, when appropriate spaces exist, the Code becomes very clear:

X = 1 + 2;

Y = 3 + 4;

Z = x + y;

Print "hello world ";

Print "z is" + z;

If (z> y + x ){

Print "error ";

}

However, too many spaces will become a burden and make the code 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 ";

}

The Code occupies the same proportion of space as its meaning.

Generally, using a small number of letters to express a large amount of Meaning often makes the code hard to read. Using a long name to express a simple meaning also makes it difficult to read the code. The amount of meaning should be proportional to the space occupied (string length.

For example, this Code does not have any readability. It should be too simple for the functions and variable names it uses.

Q = s (j, f, m );

P (q );

These names are too short compared to their meanings. However, by using a proper name, you can make the code more readable, for example:

Quarterly_total = sum (January, February, march );

Print (quarterly_total );

On the other hand, if these names are too complex than their meanings, it will make the code hard to read, for example:

Response = 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_201asas_of_today );

Like a naming rule, this rule applies to a whole block of code. We can use a simple function call to replace the functions of this code block:

Print_quarterly_total ();

In addition, this method is more readable than the previous examples. Although this function name is a little longer than other names, it contains more meaning so that we can readily accept it. In fact, it has better readability. This is because the code block represents a simple process through a large number of strings, and we can implement it through a simpler function name.

If a code block occupies a lot of space but does not actually have complex functions, you 'd better refactor this function. For example, this code is used to process 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 this is our entire program, it already has enough readability. However, if it is a small piece of code in a complex project, we 'd better refactor it to make it readable:

X_pressed = false;

Y_pressed = false;

If (input = "x "){

Handle_x (x_pressed );

}

Else if (input = "y "){

Handle_y (x_pressed, y_pressed );

}

We can even simplify it into this way through functions, so it has enough Readability:

Handle_input (input );

Reading code like "handle_input" in our project is easier than trying to understand the functions of the entire code block, because "handle_input" occupies the appropriate space, the entire code block occupies too much space. However, if we use h (input) instead, it will lead to severe ambiguity because h is too short to express a certain meaning. Similarly, a function name such as input is not a good choice.

Naming rules

A well-known software engineer once said that naming rules are the most complex issue in computer science.

The readability principle provided some clues for our naming rules. Generally, the name of a variable or function should be sufficient to express its complete meaning without being too cumbersome.

It is equally important to consider the actual use of functions or variables. Once we put these names into a line of code, will it cause the entire line of code to be too long and reduce its readability. If a function is called only once in the entire project, it can have a long enough name, and if it is in a complex expression

[Original]

Please 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 howSpaceIs occupied by letters and symbols.

What does that mean? Well, it means two things:

Code shoshould have the proper amount of white space around it. Not too much, not too little.

There shocould be the proper amount of space within a line of code to separate out the different parts. Separate actions shocould generally be on separate lines. Indentation shocould be used appropriately to group blocks of code.

With this principle, it's actuallyAbsence of codeThat makes things readable. This is a general principle of life-for example, if there was no space
At allBetween letters and words in a book, it wocould 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' tThe 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 beToo muchOrWrongSpace, 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 shocould take up space in proportion to how much meaning it has.

Basically, tiny symbols that meanLotMake code hard to read. Very long names that don't mean much also make code hard to read.
AmountOf meaning and the space taken up shocould 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 cocould 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
MoreMeaning than other pieces of code do. In fact, it's evenMoreReadable than our block of code was, by itself. Why is that? Because the code block took up a lot of space for, interval tively, 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 wowould probably be readable enough. However, if this is within a lot of other code, we cocould 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 cocould make it even more readable by grouping 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
Likeh(input)Instead, that wocould 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)Wocould not only be annoying for a programmer to type, but wocould 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. shocould
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 longFor 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 re going
Use frequently in complex expressions showould probably have a name that is short (though still long enough to fully communicate what it does ).

-Max