The art of writing readable code

This book provides a lot of dry work, and many practical suggestions are the only way to write the code. The following is my summary of the map and an overview of some chapters.

A good book is recommended to you.

Summary Mind Map

Chapter 2

The only topic in this chapter is to add information to the name. The meaning of this sentence is that the reader can obtain a lot of information only by reading the name.

• Use professional words-for example, fetch or download may be better without get, which is determined by the context.

• Avoid empty names, such as TMP and retval, unless they are used for special reasons.

• Using a specific name to describe food in a more detailed manner ---- server can start () is much clearer than canlistenonport

• Add important details to the variable name. For example, add _ MS to the variable whose value is millisecond or add raw _ to the variable to be processed if escape is still needed _.

• Use a longer name for a name with a large scope-do not use a confusing name or two letters to name variables visible between several screens. It is better to use a shorter name for a variable that only exists between several rows.

• Use Case and underline purposefully. For example, you can add "_" after the class members and local variables to distinguish them.

Chapter 3

The name is the best name without misunderstanding-the person who reads your code should understand your intention without any additional understanding. Unfortunately, many English words are multidimensional in programming, such as filter \ length and limit.

Before you decide to use a name, you need to find out what your name will be misunderstood. The best name is not wrong.

Max _ and min _ are good prefixes to define the upper limit or lower limit of an IE value. For the included range, first and last are good choices. For include/exclude ranges, begin and end are the best choices because they are most commonly used.

When naming a Boolean value, words such as is and has are used to indicate that it is a Boolean value, avoiding the use of negative words.

Be careful with users' expectations for specific words. For example, you may expect get () or size () to be a lightweight method.

Chapter 4

Everyone is willing to read beautiful code. By formatting code in a consistent and meaningful way, you can make the code easier to read and read faster.

• If multiple code blocks do similar things, try to make them have the same silhouette.

• Alignment code by column makes the code easier to browse.

• If A, B, and C are mentioned in a piece of code, do not talk about B, C, and a in another section. Select a meaningful order and always use this order.

• Use empty lines to split large pieces of code into logical "paragraphs"

Chapter 5

The purpose of the comment is to help readers understand what the author knows when writing code. This chapter describes how to discover and write down all the less obvious information blocks.

Note not required for any location:

• Facts that can be quickly inferred from the Code itself

• The "crutches-style comments" used to whitewash rotten Code (for example, poor function names)-correct the code.

The ideas you should record include:

• For the internal reason why the code is written like this rather than that ("guiding comments ").

• The defects in the Code are marked like todo: or XXX.

• The story behind a constant, why.

Thinking from the reader's standpoint:

• What part of the code is expected to make readers say, "What ?" And add comments to them.

• Add comments to unexpected behaviors of ordinary readers.

• At the file/class level, use the "view of objects" annotation to explain how all parts work together.

• Comments are used to summarize code blocks, so that readers are not lost in details.

Chapter 6

This chapter describes how to load more information into a smaller space. The following are some specific tips:

• When pronouns like "it" and "this" may refer to multiple things, do not use them.

• Describe the behavior of a function as accurately as possible.

• Carefully selected input/output examples are described in the annotations.

• Declare high-level intent of the Code, rather than obvious details.

• Use embedded comments to explain obscure function parameters.

• Concise comments using words with rich meanings

Chapter 7

There are several ways to make the control flow of code easier to read

When writing a comparison (while (bytes_expected> bytes_received), it is better to write the changed value on the left and write the more stable value on the right (while (bytes_received <bytes_expected )).

You can also rearrange the statement blocks in the IF/else statement. Generally, you must first handle the correct/simple/interesting situations. Sometimes these rules conflict, but when there is no conflict, this is the rule of thumb to be followed.

Some programming structures, such as the three-object operator, do/while loop, and Goto, often lead to poor code readability. It is best not to use them, because there is always a more clean alternative.

Nested code requires more concentrated understanding. New nesting at each layer requires the reader to "press more contexts into the stack ". They should be rewritten into more "linear" code to avoid nesting.

Early return usually reduces nesting and keeps the code clean. "Protection statements" are especially useful when processing simple cases at the top of a function.

Chapter 8

It is difficult to think about huge expressions. This chapter provides several sharding expressions so that you can digest them over time.

A simple technique is to introduce "Interpretation variables" to represent long subexpressions. This method has three advantages:

• It splits a huge expression into small segments.

• It describes sub-expressions with simple names to document code.

• It helps readers identify the main concepts in code

Another technique is to use the demorgan theorem to operate logical expressions. This technique can sometimes rewrite boolean expressions in a more concise way (for example, if (! (&&! B) to If (! A | B )).

This chapter provides an example of splitting a complex logical condition into a small statement. In fact, in all the improved instance code in this chapter, there are no more than two values in all if statements. This is an ideal situation. This may not always happen-sometimes the problem needs to be "Reversed" or the opposite of the target needs to be considered.

Finally, although this chapter is about splitting independent expressions, these techniques are often applied to large code blocks. Therefore, you can boldly split complicated logic wherever you see it.

Chapter 9

This chapter describes how variables in a program are quickly accumulated and become difficult to trace. You can reduce the number of variables and make them as lightweight as possible to make the code more readable. Specific

• Reduce variables, that is, those that impede the variable. We have provided several examples to demonstrate how to eliminate the "intermediate result" variable by processing the result immediately.

• Reduce the scope of each variable, the smaller the better. Move the variable to a place where there is at least code to see it. Not seeing, don't bother.

• It is better to write the variable only once. Variables (or const, final, and constants) that only set values once make the code easier to understand.

Chapter 10

A simple summary in this chapter is "Separating general code from proprietary project code ". The result is that most of the Code is normal code. By creating a large set of libraries and helper functions to solve general problems, the rest is just the core part that differentiates your program.

This technique is helpful because it enables programmers to focus on small and well-defined issues that have been separated from other aspects of the project. The result is that solutions to these subproblems tend to be more complete and correct. You can also reuse them later.

Chapter 2

This chapter provides a simple technique for organizing code: One thing at a time.

If you have code that is hard to read, try to list all the tasks it has done. Some tasks can easily become independent functions (or classes ). Others can simply become the logical "paragraph" in a function ". How to split these tasks is not as important as they are already separated. The difficulty is to accurately describe all these things that your program has done.

Chapter 2

This chapter discusses a simple technique to describe a program in a natural language and then use this description to help you write more natural code. This technique is surprisingly simple, but powerful. The words and phrases used in the description can also help you find out which sub-problems can be split.

However, this process of "speaking things in natural language" can not only be used to write code. For example, a university computer lab claims that when a student needs someone to debug the program, he must first explain the problem to a dedicated teddy bear in the corner of the room. Surprisingly, by describing the problem out loud, the student can often find a solution. This technique is called the Rubber Duck technique"

Another perspective is: if you cannot describe the problem or use words for design, it is estimated that something is missing or something is missing definition. Turning a question (or idea) into a language can really make it more specific.

Chapter 2

Adventure and excitement-not what Jedi pursues-master Yuda

This chapter describes how to write less code, the better. Each line of New Code requires testing, writing documents, and maintenance. In addition, the more code in the code library, the more "heavy" it is, and the more difficult it is to develop on it.

You can avoid writing new code using the following methods:

• Remove unnecessary functions from the project and do not over-design them.

• Reconsider the requirements to solve the simplest version problem, as long as the work can be completed.

• Regularly read the entire API of the standard library to maintain familiarity with them.

 

Chapter 2

In the test code, readability is still important. If the test is readable, the result is that they will become easy to write, so you will write more tests. In addition, if you design the fact code to be easily tested, the entire design of the Code will become better.

The following are several key points for improving the test:

• The highest layer of each test should be more concise and better. It is best to use a line of code to describe the input/output of each test.

• If the test fails, the error message sent by it should make it easy for you to track and correct this bug.

• Test inputs that are the easiest to use and fully utilize code.

• Give the test function a fully descriptive name to clarify what is measured in each test. Instead of test1 (), use a name like test _ <functionname>-<situation>.

The most important thing is to make it easy to modify and add new tests.

 

 

Books about writing high-quality code

Code complete: A Practical Handbook of software constructionm, 2nd edition, by Steve McConnell

A rigorous big part is about all aspects of software construction, including code quality and others.

Refactoring: improving the design of existing code, by Martin Fowler et al.

A good book on the philosophy of incremental code improvement involves the specific classification of many different refactoring methods and the steps required to make these changes without compromising anything as much as possible.

The practice of programming, by brain kernighan and Rob Pike

I have discussed many programming aspects, including debugging, testing, portability and performance. There are many code examples.

The pragmatic programmer: From journeyman to master, by Andrew hunt and David Thomas

A series of good programming and engineering principles are organized according to short discussions.

Clean code: A Handbook of Agile Software craftmanship, by Robert C. Martin

Similar to this book (but specifically for Java), it also expands on other topics such as error processing and concurrency.

 

Books on various programming topics

Javascript: the good parts, by Douglas crockford

We think the spirit of this book is similar to that of ours, although it is not directly about readability. It is a clear subset of how to use JavaScript language that is not prone to errors and easier to understand.

Effective Java, 2nd edition, by Joshua Block

An outstanding book is about making your Java programs easier to read and have fewer bugs. Although it is about Java, many of these principles apply to all languages. It is strongly recommended.

Design Patterns: Elements of reusable object-oriented software, by Erich Gamma, Richard Helm, Ralph Johnson, and Jon vlissides

This book is the original source for software engineers to discuss general-purpose languages such as patterns for programming. As a general list of useful models, it helps programmers avoid frequent traps when solving their own thorny problems for the first time.

Programming pearls, 2nd edition by Jon beentley

A series of articles on real software issues. Each chapter has insights into solving problems in the real world.

High Performance Web sites, by Steve Souders

Although this is not a programming book, it is worth noting because it describes several methods to optimize the website without having to write a lot of code.

Joel on software: And on diverse and..., by Joel Spolsky

A few excellent articles from http://www.joelonsoftware.com. Spolsky's work involves many aspects of software engineering and has profound insights on many related topics. Be sure to read "Things You shoshould never do, Part I" and "The Joel test: 12 steps to better code"

The art of writing readable code