Reprinted please indicate the source: http://blog.csdn.net/horkychen
(Excerpt from msdn-coding techniques and programming practices)
Names)
Naming is most helpful for understanding the logical structure of a program. A name description is "what" is more important than "how. Naming can avoid exposing the underlying implementation, thus retaining an abstract layer, simplifying the complexity of the program. For example, you can use getnextstudent () instead of getnextarrayelement ().
The purpose of a naming rule is to repeat the naming rule based on its purpose. The name must be concise and clear. For programming (programmatically), naming is to distinguish each other easily. An accurate name is easy to read and easy to understand. However, the specific naming method is still subject to the language used and standards that follow.
The following are recommended naming techniques:
Routine (routines, process or function)
- Avoid names that may be misunderstood, mostly subjective terms, such as the analyze () function or variable xxk8. Such names are ambiguous.
- In an object-oriented language, the class attribute name does not need to contain the class name. Such as book. booktitle. You can use book. Title instead.
- Use the verb-noun (verb-object) structure to name the method, such as calculateinvoicetotal ().
- In languages that allow function overloading, all overloading should perform similar functions. For languages that do not allow function overloading, set a naming standard for functions with similar functions.
Variable)
- If necessary, append the calculation qualifier (avg, sum, Min, Max, index) after the variable name ).
- Use antonyms in variable names, such as min/max, begin/end, and open/close, and get/set.
- Variable names connected by several words, in case-insensitive format to simplify them. In addition, to help distinguish between variables and routines (functions, routine), the routine name uses the Pascal naming method, and the first letter of all words is in upper case (calculateinvoicetotal ). Variable names use camel casing (for example, documentformattype). Except for the first letter, all the other words except the first letter are capitalized.
- The Boolean variable name must be true or false, for example, fileisfound.
- Do not use flag when naming status variables. They may have more than two values than Boolean values. You can use a more descriptive name than documentflag, such as documentformattype.
- Even if only one temporary variable appears in several lines of code, try to use a meaningful name. Only single-letter variables such as I and j are used as small cyclic variables.
- If the Hungary naming method is used, a clear list of standard prefixes is defined to facilitate the use by developers in the project. For more information, see "Hungarian notation"
- You can add a symbol to the variable name to identify the scope, such as the prefix.G _Global variables andM _Module/class member variable.
- Constants should all be capitalized and separated by underscores. For example, num_days_in_week. Enumerated variables should have a common prefix. Such as font_arial or font_roman.
Data Table (tables)
- When naming a table (tables), it is named in the singular form. For example, you should use employee instead of employees.
- Do not duplicate table names when naming columns in a table. For example, do not define the field employeelastname in a table named "employee.
- Do not include data types in column names. This can simplify the work when changing data types in the future.
Others (Miscellaneous)
- Use less abbreviations. If yes, you must maintain consistency. The abbreviation should have only one meaning, and the corresponding word should also have only one abbreviation. For example, if Min is used to minimize the number of minutes, do not make it short for minute.
- When naming a function, it can contain a description of the return value. For example, getcurrentwindowname ().
- File and folder names, just like program names, should accurately describe what they serve.
- Avoid using similar names for different types of elements, such as the processsales () function and the variable iprocesssales.
- Avoid homophone naming to facilitate code review, such as write and right.
- When naming an element, avoid using words that are often misspelled. Of course, we also need to know the differences between American English and British English, such as color/color (both colors) and check/cheque (both checks ).
- Avoid using print symbols to identify the data type. For example, $ represents a string or % represents an integer.
Comments)
There are two types of software documents: external and internal. External documents are outside the source code, such as specifications, help files, and design files. Internal documents are in the source code and are composed of comments written by developers during development.
The biggest challenge is how to ensure that annotations can be updated synchronously with source code. Although correct comments of source code won't affect the running of programs, It is priceless for software that is particularly complicated or cumbersome to maintain.
The following are recommended comments:
- Update comments synchronously when modifying code.
- Standard Annotation Templates (such as doxygen annotations) are provided at the beginning of each method or function to indicate the purpose, assumptions, and limitations of the routine. The annotation template should be a simple introduction to understand the purpose and functions of methods or functions.
- Avoid adding comments at the end of the code line, which makes the code more difficult to read. However, you can add comments after the variable declaration. In this case, you can use a tab to align all row comments.
- Avoid custom clutter comments methods, such as asterisks in the entire line. You can use spaces to separate code and comments.
- Avoid printing symbols (such as typographical frame, $, #, and %) around the annotation block ). You may think it looks nice, but it is difficult to maintain it.
- Before the official release, remove all temporary or irrelevant comments to avoid affecting future maintenance work.
- If you need to comment out a complex piece of code, you should first check to see if you can rewrite (refactor ). Try not to comment out bad code, but to refactor it. A balance must be sought between performance and maintainability.
- The purpose of a complete sentence is to clarify the Code, rather than regenerate the ambiguity.
- Comment out your code in time, because you will not have time to do it in the future. In addition, code repeat is more effective than six weeks.
- Do not include additional comments, such as humorous narration or complaints against the company.
- Use annotations to explain the intent of the Code, rather than the translation of the Code.
- Comment out the hidden parts of any code.
- To prevent repeated issues, add comments to the Code for bug fixes and solutions. This is especially important for the team.
- Add comments to codes that contain loops and logical branches. These are key points to help readers read the code.
- Use spaces to separate comments, which can be highlighted and easier to locate. (Separate comments from comment delimiters with white space. Doing so will make comments stand out and easier to locate when viewed without color clues .)
- Throughout the program, a uniform style is used and comments are added with consistent punctuation and structure.
