Note
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.
