Improve code readability comments practical skills

Many programmers often do not pay attention to the readability of the code at the time of writing, so that other people spend more time reading the code. In fact, as long as the programmer when writing code, note the code annotate, and at a reasonable format to annotate the code, so to facilitate other people looking at the code, but also the convenience of their own later. Share annotated below ten tips:
add comments to each code block, and each layer using a uniform annotation methods and style. For example:
· for each class: includes summary information, author information, and last modified date;
* for each method: Includes uses, functions, parameters and return values.
In team work, the use of standardized notes is particularly important. Of course, the use of norms and annotation tools (such as C # in the XML, Java in the Javadoc) can better promote the annotation job done better.
If there are multiple code blocks, and each block of code to complete a single task, add in front of each block of code comments to explain what the code to the reader.
Examples are as follows:
// All the Check Data Records that
// are correct
the foreach (in the Record Record Records)
... {
IF (rec.checkStatus () == Status.OK)
... {
...
// Now the begin WE Perform to
// Transactions
the Context the ApplicationContext new new CTX = ();
ctx.BeginTransaction ();
...
If each line of multiple lines of code have to add comments, add a comment the line after each line of code, it will be easy to understand. For example:
const MAX_ITEMS = 10; // Number of packets maximum
const the MASK = 0x1F; // the TCP 'bit mask
when the partition code and the comments, some developers use the tab key, while others use the spacebar. However, due to inconsistencies in performance between the tab and the IDE editor tool, so the best way is to use the spacebar.
Avoid the obvious comment: Write these useless comments will waste your time, and transfer the reader to understand the details of the code.
IF (A == 5) // IF the equals 5 A
counter = 0; // counter to the SET at The ZERO
avoid rude comments, such as: "Attention, stupid user will enter a negative number" or "just fix this for the initial issue of incompetent hands of developers. " Such comments reflect the author how bad it is, you never know who will read these comments, may be: your boss, client, or are you just insulted incompetence developers.
Do not write too much and difficult to understand the need to turn and comments. Avoid ASCII art, funny, poetic, hyperverbosity comment. In short, keep the comments straightforward.
Some people believe that comments should be written to the degree of non-programmers to understand. While others argue that as long as Notes developers can understand on the line. In any case, Successful Strategies for Commenting Code has been defined and spelled out the comments of consistency and for the readers. Personally, I would suspect that most non-programmers to read code, so comments should be for other developers who.
When working in a team, in order to facilitate communication with other programmers, we should adopt a consistent set of tags to annotate. For example, many teams with TODO label indicates that the code segment also requires additional work.
Estimate int (int X, Y int)
... {
// the TODO: Implement Calculations The
return 0;
comment tags do not avoid for interpreted code, it just passed or attention message. If you use this technique, remember to track and identify what information is represented.
When writing code to add comments, then your mind is clear and complete idea. If you add comments in the code Last but not least, it will cost you more than twice as long. And "I do not have time to write notes," "I'm busy" and "project has been postponed," It's all an excuse to write notes and do not want to find. Some developers think we should write comments before code, to sort things out. For example:
public void the ProcessOrder ()
... {
// the Make the Sure Products's are the Available at The
// the Check that the Customer at The IS! Valid
// the Send to the Order at The Store at The
// the Generate Bill
when the comments in the code, taking into account not only the future maintenance you look at the code developer, but you also might look. By Phil Haack master's words: "Once the line of code is displayed on the screen, you will become defenders of this code." Therefore, for our well-written (poor) comments, we will be the first beneficiaries (victims).