The coding coding method incorporates many aspects of software development. Although they usually have no effect on the functionality of the application, they are useful for improving the understanding of the source code. This takes into account all forms of source code, including programming, scripting, tagging, and query languages.
The coding method defined here is not recommended to form a set of fixed coding standards. Instead, they are intended as guidelines for developing coding standards for specific software projects.
The coding method is divided into three parts:
naming
Naming schemes are the most powerful help for understanding the logical flow of an application. The name should say "what" rather than "how." You can preserve the abstraction layer of simplified complexity by avoiding the name of the public base implementation that will change. For example, you can use Getnextstudent () instead of getnextarrayelement ().
The naming principle is that the difficulty of choosing the correct name may indicate the need to further analyze or define the purpose of the item. Make the name long enough to be meaningful and short enough to avoid being verbose. Unique names are programmed to be used only to separate areas. Strong names are meant to help people read, so it makes sense to provide names that people can understand. However, make sure that the name you select conforms to the rules and standards of the applicable language.
The following are the recommended naming methods.
Routines
- Avoid difficult names that can easily be interpreted subjectively, such as analyzethis () for routines, or xxK8 for variables. Such a name can cause ambiguity, not just abstraction.
- In an object-oriented language, it is superfluous to include a class name in the name of a class property, such as Book.booktitle. Instead, you should use Book.title.
- Use the verb-noun method to name a routine that performs a specific action on a given object, such as Calculateinvoicetotal ().
- In languages that allow function overloading, all overloads should perform similar functions. For languages that do not allow function overloading, establish a naming standard that makes similar functions happen.
Variable
- Append the calculation qualifier (AVG, Sum, Min, Max, Index) to the end of the variable name as appropriate.
- Use complementary pairs in variable names, such as Min/max, Begin/end, and Open/close.
- Since most names are constructed by connecting several words, use a mixed-case format to simplify their reading. In addition, to help differentiate between variables and routines, use Pascal casing for routine names (Calculateinvoicetotal), where the first letter of each word is capitalized. For variable names, use camel case handling (documentFormatType), where the first letter of each word is capitalized except for the first word.
- Boolean variable names should contain is, which means yes/no or true/false values, such as Fileisfound.
- When naming a state variable, avoid using terms such as Flag. A state variable differs from a Boolean variable where it can have more than two possible values. Instead of using Documentflag, you use a more descriptive name, such as documentFormatType.
- A meaningful name is still used even for variables that may be short-lived in a few lines of code. Use a single letter variable name, such as I or J, for a short loop index only.
- Do not use literal digits or literal strings, such as for i = 1 to 7. Instead, you use named constants, such as for i = 1 to Num_days_in_week in order to maintain and understand.
Table
- When naming tables, names are represented in the singular form. For example, use Employee instead of Employees.
- Do not repeat the name of a table when you name a column in a table, for example, to avoid using a field named Employeelastname in a table named Employee.
- Do not include data types in the name of the column. If it is necessary to change the data type later, this will reduce the amount of work.
Microsoft SQL Server
- Do not add an SP prefix to the stored procedure, which is reserved for identifying system stored procedures.
- Do not prefix a user-defined function with a fn_ prefix that is reserved for identifying built-in functions.
- Do not prefix extended stored procedures with XP_, which is reserved for identifying system extended stored procedures.
Miscellaneous
- Minimize the use of abbreviations, but instead use the abbreviations that are created in a consistent manner. Abbreviations should have only one meaning; Likewise, each abbreviation should have only one abbreviation. For example, if you use min as the abbreviation for minimum, you should do so in all places, and do not use min as an abbreviation for minute.
- Include a description of the return value, such as Getcurrentwindowname (), when the function is named.
- As with procedure names, the names of files and folders should also describe exactly what they are used for.
- Avoid reusing names for different elements, such as routines named Processsales () and variables named Iprocesssales.
- Avoid homonym words such as write and right when naming elements, in case of confusion when checking code.
- When naming elements, avoid the use of universally misspelled words. In addition, you should be aware of the differences between regional spellings, such as Color/colour and Check/cheque.
- Avoid printing marks to identify data types, such as using $ to represent a string or an integer with%.
Notes
Software documents exist in two forms: external and internal. External documents (such as specifications, help files, and design documents) are maintained outside the source code. Internal documentation consists of comments that developers write in the source code at development time.
Regardless of the availability of external documents, the source code list should be able to exist independently because hard-copy documents may be misplaced. External documents should consist of specifications, design documents, change requests, error histories, and coding standards used.
One of the challenges with internal software documentation is to ensure that annotations are maintained and updated at the same time as the source code. Although it is not useful to correctly annotate source code at run time, it is invaluable to developers who must maintain a particularly complex or troublesome piece of software.
The following are the recommended annotation methods:
- If you are developing with C #, use the XML document feature. For more information, see: XML documentation.
- When you modify your code, always keep the comments around your code up to date.
- At the beginning of each routine, it is helpful to provide a standard annotation sample to indicate the purpose, assumptions, and limitations of the routine. The annotation sample should be a brief introduction to explain why it exists and what it can do.
- Avoid adding comments at the end of lines of code, and end-of-line comments make the code more difficult to read. However, when you annotate a variable declaration, the End-of-line annotation is appropriate, and in this case, all end-of-line comments are aligned at the Common tab stop.
- Avoid clutter of annotations, such as the whole planet. Instead, you should use whitespace to separate the annotations from the code.
- Avoid adding a printing box around the block annotation. It may look beautiful, but it's difficult to maintain.
- Before deployment, remove all temporary or unrelated comments to avoid confusion in future maintenance efforts.
- If you need to use annotations to interpret complex sections of code, check this code to determine if it should be overridden. Do everything possible not to annotate code that is difficult to understand, but to rewrite it. Although you should not generally sacrifice performance to make your code simpler for people to use, you must maintain a balance between performance and maintainability.
- Use a complete sentence when writing a comment. Annotations should clarify the code and should not add ambiguity.
- Comment As you write your code, because you probably won't have time to do so later. In addition, if you have the opportunity to review the code that has been written, what seems obvious today may not be obvious after six weeks.
- Avoid unnecessary or inappropriate comments, such as the less important notes of humor.
- Use annotations to interpret the intent of the code. They should not be used as online translations of code.
- Comment on anything that is not very obvious in the code.
- To prevent recurring problems, you always use annotations for bug fixes and resolution code, especially in a team environment.
- Use annotations for code that consists of loops and logical branches. These are the main aspects of helping source code readers.
- In the entire application, the annotation is constructed using a uniform style with consistent punctuation and structure.
- Separate the annotations with the annotation separator with whitespace. When you view a comment without a color hint, this makes the annotation clear and easy to find.
format
Formatting makes the logical structure of the code obvious. Taking the time to make sure that the source code is formatted in a consistent and logical manner is helpful for you and other developers who must decrypt the source code.
The following are some of the recommended formatting methods.
- Establish a standard indentation size, such as four spaces, and use this standard consistently. Aligns the section of code with the specified indentation.
- Use the Monotype font when publishing hardcopy versions of your source code.
- Vertically align the opening and closing parentheses at the position where the brackets are aligned, such as:
for (i = 0; i < i++) {...}
You can also use italic styles, where the opening parenthesis appears at the end of the line, and the closing parenthesis appears at the beginning of the line, such as:for (i = 0; i < i++) {...}
Regardless of which style you choose, use that style throughout your source code.
- Indents the code along the logical structure line. Without indentation, the code will become difficult to understand, such as:
If ... ThenIf ... Then ... Elseend IfElse ... End If
Indenting code produces more readable code, such as:If ... Then If ... Then ... Else ... End IfElse ... End If
- Create the maximum length for comments and code to avoid having to scroll the source editor and provide a neat hard copy representation.
- Use spaces before and after most operators, and doing so does not change the intent of the code. However, the pointer notation used in C + + is an exception.
- Use whitespace to provide structural clues to the source code. Doing so creates code "segments" that help readers understand the logical segmentation of the software.
- When a row is divided into rows, it is clear that no subsequent rows are incomplete by placing the concatenation operator at the end of each line rather than the beginning.
- If appropriate, the statements placed on each line are avoided by more than one line. Exceptions are loops in C, C + +, C #, or JScript, such as for (i = 0; i < i++).
- When writing HTML, establish standard markup and attribute formats, such as all tags are uppercase or all properties are lowercase. Alternatively, adhere to the XHTML specification to ensure that all HTML documents are valid. Although you need to compromise the file size when creating a Web page, you should use quoted property values and closing tags for ease of maintenance.
- When you write an SQL statement, use ALL caps for the keyword, and use a case mix for database elements such as tables, columns, and views.
- Logically divide the source code between the physical files.
- Placing each major SQL clause on a different line makes it easier to read and edit statements, for example:
SELECT FirstName, lastnamefrom customerswhere state = ' WA '
- Divide large, complex sections of code into smaller, easy-to-understand modules.
