Six Rules for Writing Clean Code

yanglsw

- By Matt Gordon

As embedded systems developers, many of us are veterans of multiple programming courses. In college, we received instruction on a vast assortment of different algorithms and data structures.
Most of us were also taught the semantics of at least one high-level programming language. There are surprisingly few engineers, though, who have received significant instruction on the fundamental topic of coding style.
Programming courses teach what can and can't be done with a particular language, but they often fail to demonstrate what should be done in order to produce clear-cut, manageable code.
The exclusion of this topic from programming curricula does not indicate that coding style is inconsequential. To the contrary, the style in which a program is written affects how that code functions, and determines whether or not it can be easily supported.
Developers who have adopted an effective style produce software that other programmers can readily understand and update. On the other hand, developers who lack such a style turn out code that causes innumerable headaches for the engineers who are responsible for its maintenance.
What actually constitutes an effective coding style? Six general rules for writing clean code are provided below. These guidelines will help you steer clear of the problems that poor coding style creates.

Rule #1. Use pithy comments
When other engineers attempt to discern how your code works, they'll likely turn to your comments. Thus, you should make sure that these comments form an accurate description of the code. You should also avoid stating what would be obvious to another engineer. The first of the below C comments provides its reader with useful information, but the second is frivolous. (Constants are hard-coded in the below code and elsewhere in this article. You should normally use #define constants in place of such hard-coded values.)
while (usb_pkt_rdy == 0)  {   /* Wait until at least one packet has been received */

x = 0;                                     /* Set x to 0                                                                  */


Rule #2: Assign intuitive names to variables and functions
You should use names to indicate functionality. The name filter_coeff, for instance, would be appropriate for a variable that is a filter coefficient. In the commenting example above, the name x reveals little about what that variable does.

Rule #3: Make ample use of white space
To a C compiler, white space simply delimits tokens. Accordingly, extra spaces and newlines in your application may seem to be of small importance.
In C and many other high-level languages, though, white space can help other developers to more easily understand your code. Although the two loops shown below are identical from the perspective of a compiler, the functionality of the second loop is clearer to human readers of the code. (Importantly, the Tab key was not used to indent the second loop. Since the Tab character does not expand identically on all machines, it should be avoided.)

Rule #4: Don't make your code unnecessarily complex
A single line of C code can have multiple side effects. Typically, though, a lengthy line of code that updates multiple variables is more difficult to understand than multiple, simple lines of code that accomplish this same objective.
Thus, you should try to limit the number of actions performed by each line of your code. You should likewise strive for simplification when declaring functions; excessively lengthy routines should be broken into multiple parts.
For the compiler, multiple statements on one line or single statement on multiple lines will produce the same code density. As it is easier for the reader to have one statement per line, this is the recommendation, which has no impact on code efficiency.

Rule #5: Be explicit
So that other developers will be able to quickly discern what each line of your code does, you should eschew syntax that obscures meaning. For example, in comparison statements that involve zero, you should avoid the syntax shown in the first of the below if statements.
        if (!tx_val) {
            err_cnt++;
        }
Instead, your code should resemble the second if statement below. This statement clearly indicates that the variable tx_val is being compared to zero.
        if (tx_val == 0) {
            err_cnt++;
        }

Rule #6. Apply rules uniformly
Simply put, clean code is consistent code. To make sure that your style is consistent, you should use a coding standard, a formal document that elaborates on the type of rules that this article summarizes.
For an example coding standard, you can visit the Web site of embedded software provider Micriµm. There, you can download the standard that guides the efforts of each of Micriµm's software developers. This coding standard is available free of charge.

Matt Gordon, Technical Marketing Engineer, at [url=http://www.embedded.com/columns/technicalinsights/%3Fhttp://www.micrium.com%3F]www.micrium.com[/url] has several years of experience as an embedded software engineer, and is responsible for explaining the nuances of this the company's software to Micriµm's partners and customers. Matt holds a bachelor's degree in computer engineering from Georgia Tech.

mjj_jjm2009

有高手能直接翻成中文的么?

sulerzh

为了学习币啊