C # writing specifications

C # writing specifications
I. Naming
The naming scheme is the most influential help for understanding the logical flow of an application. The name should indicate "what" rather than "how ". By avoiding the name of the public basic implementation (which may change), you can retain the abstract layer that simplifies the complexity. For example, you can use GetNextStudent () instead of GetNextArrayElement ().
Naming principles:
Selecting the correct name may indicate the purpose of further analysis or definition. Make the name long enough to make sense, and be short enough to avoid being too long. The unique name is only used to differentiate items. Strong performance names are used to help people read; therefore, names that people can understand are meaningful. However, make sure that the selected name complies with the rules and standards of the applicable language.
The following are recommended naming methods.
1. Methods, attributes, and variable specifications
Avoid obscure names that are easily subjective, such as the aspect name AnalyzeThis () or the attribute name xxK8. Such a name may result in ambiguity.
In an object-oriented language, it is unnecessary to include a class name in the class attribute name, such as Book. BookTitle. Instead, use Book. Title.
Use the verb-Noun method to name the routines that perform specific operations on a given object, such as CalculateInvoiceTotal ().
In languages that allow function overloading, all overloading should execute similar functions.
If appropriate, add the calculation qualifier (Avg, Sum, Min, Max, Index) at the end or at the beginning of the variable name ).
Use complementary pairs in variable names, such as min/max, begin/end, and open/close.
Since most names are constructed by concatenating several words, use a mix of upper and lower cases to simplify their reading. In addition, to help distinguish between variables and routines, use CalculateInvoiceTotal for the routine name. the first letter of each word is in uppercase. For variable names, use camel case sensitivity (documentFormatType). The first letter of each word except the first word is capitalized.
The Boolean variable name should contain Is, which means Yes/No or True/False values, such as fileIsFound.
Do not use Terminologies such as Flag when naming state variables. A state variable has more than two possible values than a Boolean variable. Instead of using documentFlag, use a more descriptive name, such as documentFormatType. (This item is for reference only)
Even for variables that may only have a short lifetime in several lines of code, they still use meaningful names. Only use single-letter variable names for short-cycle indexes, such as I or j.
If possible, do not use the original numeric or string, such as For I = 1 To 7. Instead, we use a naming constant, For example, For I = 1 To NUM_DAYS_IN_WEEK, To facilitate maintenance and understanding.
Ii. code writing specifications
Formatting makes the logic structure of the code very obvious. It takes time to make sure that the source code is formatted in a consistent logic, which is of great help to you and your development team and other developers who will maintain the source code in the future.
The following are recommended formatting methods.
Create a standard indent size (such as four spaces) and use this standard consistently. Align the code section with the specified indentation.
Use a specific font and font size when releasing a hard copy version of the source code (New ,, ).
Align the Left and Right brackets vertically at the positions of the brackets, such:
For (I = 0; I <100; I ++)
{

}
You can also use the skewed style, that is, the left parenthesis appears at the end of the row, and the right parenthesis appears at the beginning of the row, such:
For (I = 0; I <100; I ++ ){

}
Regardless of the selected style, use that style throughout the source code.
Indent the code along the logical structure line. Without indentation, the Code becomes hard to understand, such:
If (expression)
{
//
// Enter your code block here;
//
}
If (expression)
{
//
// Enter your code block here;
//
}
Else
{
//
// Enter your code block here;
//
}
Indent code generates code that is easier to read, such:
If (expression)
{
If (expression)
{
//
// Enter your code block here;
//
}
Else
{
//
// Enter your code block here;
//
}
}
Create the maximum line length for comments and code to avoid having to scroll through the source code editor and provide a neat hard copy representation.
Spaces are used before and after most operators. In this case, the intent of the Code is not changed. However, the pointer representation used in C ++ is an exception.
Use blank space to provide structure clues for source code. This will create code segments to help readers understand the logical segments of the software.
When a line of content is too long and must be changed, the indent format should be used in the next line feed code, as shown below:
String inserString = "Insert Into TableName (username, password, email, sex, address )"
+ "Values ('soholife', 'chenyp', 'soholife @ sina.com ', 'male', 'shenzhen Futian ')";
If appropriate, avoid placing more than one statement on each row. The exception is a loop in C, C ++, C #, or JScript, such as for (I = 0; I <100; I ++ ).
Standard tag and attribute formats are created when HTML is compiled. For example, all tags are in upper case or all attributes are in lower case. Another method is to adhere to the XHTML specification to ensure that all HTML documents are valid. Although the file size needs to be compromised when creating a Web page, attribute values and ending tags with quotation marks should be used for easy maintenance.
When writing SQL statements, all keywords are capitalized, and database elements (such as tables, columns, and views) are case-insensitive.
Logically divide source code between physical files.
Place each major SQL clause on different rows, which makes it easier to read and edit statements, for example:
SELECT FirstName, LastName
FROM MERs
WHERE State = 'wa'
Divides large complex code segments into small and easy-to-understand modules.
3. 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 documents are composed of comments written by developers in the source code during development.
The availability of external documents is not considered. The source code list should be independent because the hard copy document may be put in the wrong place. External documents should consist of specifications, design documents, change requests, error history records, and encoding standards used.
One difficulty of the internal software documentation is to ensure that the comments are maintained and updated at the same time as the source code. Although correct annotation of source code is useless at runtime, It is invaluable to developers who must maintain extremely complex or troublesome software snippets.
The following are recommended comments:
If C # is used for development, use the XML document format, as described in the following method:
/// <Summary>
/// Get someone's age
/// </Summary>
/// <Param name = "userName"> User name </param>
/// <Returns> User age </returns>
Public int GetUserAge (string userName)
{
//
// Write your program code here
//
}
When you modify the code, always keep the comments around the code up-to-date.
At the beginning of each routine, it is helpful to provide standard annotation samples to indicate the purpose, assumptions, and limitations of the routine. The annotation sample should be a brief introduction to why it exists and what it can do.
Avoid adding comments at the end of the code line. comments at the end of the line make the code harder to read. However, it is appropriate to comment at the end of a row when the variable declaration is annotated. In this case, the comment at the end of all rows is aligned at the common tab.
Avoid messy comments, such as a whole planet number. Instead, empty comments should be separated from the code.
Avoid adding a printed box around the block comment. This may look pretty, but it is difficult to maintain.
Remove all temporary or irrelevant comments before deployment to avoid confusion during future maintenance work.
If you need to use annotations to explain complex code sections, check the code to determine whether it should be overwritten. Rewrite the code without comments that are hard to understand. Although it is generally not necessary to sacrifice performance to make the code easier for people to use, it is necessary to maintain a balance between performance and maintainability.
Use complete sentences when writing comments. Comments should clarify the code without adding meaning.
Comments when writing code, because it is likely that there is no time to do so in the future. In addition, if you have the opportunity to review the code you have written, it seems obvious that six weeks later may not be obvious.
Avoid unnecessary or inappropriate comments, such as humorous and non-main comments.
Use annotations to explain the intent of the Code. They should not be used as online translation of code.
Comment out nothing obvious in the code.
To prevent repeated problems, the code for error fixes and solutions always uses annotations, especially in the team environment.
Use comments for codes composed of loops and logical branches. These are the main aspects to help source code readers.
Throughout the application, comments are constructed using a unified style with consistent punctuation and structure.
Separate comments from comments with comments in blank spaces. When you view comments without a color prompt, this will make the comments obvious and easy to find.