Note is undoubtedly the fastest way to let others know your code as quickly as possible, but the purpose of writing a comment is not just to "explain what the code has done ", more importantly, try to help the code reader understand the code as much as the author does.
When you write code, there will be a lot of valuable information in your mind, but when others read your code, this information has been lost, and all they see is the current code.
If the IDE provides the annotation format, try to use the format provided by the IDE; otherwise, use "//" to annotate. Class, attribute, and method annotations use the format automatically generated by input "//" in Visual Studio.
- Class annotation conventions
/// <Summary>
/// Class description
/// </Summary>
Public class binarytree
- Class property annotation conventions
/// <Summary>
/// Attribute description
/// </Summary>
Public int nodescount {Get; private set ;}
- Method annotation Convention
/// <Summary>
/// Method description
/// </Summary>
/// <Param name = "parentnode"> parameter description </param>
/// <Returns> return value description </returns>
Public int computechildnodescount (binarynode parentnode)
- Single line comment, comment rows <3 rows use
// Single line comment
- Multi-line comment, used when 2 <comment rows <= 10
/* Multi-line comment 1
Multi-line comment 2
Multi-line comment 3 */
- Comment block, 10 <used to comment the number of rows, 50 *
/*************************************** ************
* Code block comment 1
* Code block comment 2
*......
* Code block Comment 10
* Code block comment 11
**************************************** ***********/
- Conventions on when to write comments
- In the following three cases, all classes, class attributes, and methods must be annotated according to the preceding format.
- The client attaches great importance to code comments.
- We need to provide the API documentation automatically generated by code annotations.
- Currently, the public core module is written.
- If the customer does not have special requirements for the annotations, add the annotations as discussed below. Do not add unnecessary comments.