Self-summarized C # Coding specification--4. Comments

• Comments

Annotations are no doubt the quickest way to get people to know your code as quickly as possible, but the purpose of writing comments is not simply "explaining what the code does", but more importantly to help code readers understand the code as much as the author does.

When you write code, there is a lot of valuable information in your mind, but when someone reads your code, the information is lost, and all they see is the code in front of them.

• Annotation conventions

If the IDE provides a comment format, use the format provided by the IDE as much as possible, or use "//" to annotate. Comments for classes, properties, and methods are used in Visual Studio to automatically generate a format that is entered as "///".

• class Annotation conventions

<summary>

Class description

</summary>

public class BinaryTree

• Class Property Annotation Conventions

<summary>

Property Description

</summary>

; }

• Method Annotation Conventions

<summary>

Method description

</summary>

<param name= "parentnode" > Parameter Description </param>

<returns> return Value Description </returns>

ParentNode)

• Inter-code Annotation Conventions

1. Single-line comment, Comment line count <3 row use

   Single-line Comment

2. Multi-line Comment,2< Comment line number <=10 when used

   /* Multiline Comment 1

   Multi-line Comment 2

   Multi-line Comment 3*/

3. Comment Block,10< comment line number with 50 *

   /***************************************************

   * Code block Comment 1

   * Code block Comment 2

   *    ......

   * Code block Comment 10

   * Code block Comment 11

   ***************************************************/

• When to write a convention for annotations

1. Here are three things we need to write comments in all classes, class properties, and methods as described in the preceding format
   1. Client side has a high degree of emphasis on code annotations
   2. We need to provide an automatically generated API documentation for code annotations.
   1. The public core module is currently being written
2. If the client does not have a special request for comments, then the comments are only as needed, as discussed later in this article. Don't add unnecessary comments.

• Conventions for common annotation identities

Here is the agreement after the team commonly used several annotation logo and meaning:

TODO: things I haven't done yet.

Fixme: Known Issues

HACK: Have to adopt a rough solution to a problem

XXX: Dangerous! There are important questions here.

Ask team members to configure FIXME and XXX as high-priority comments in Visual Studio themselves.

Steps:tools->options->environment->task List->tokens->add->ok

Once the configuration is complete, we can see the tasks that exist in the code in the comments option in the Task List (ctrl+w,t) window.

• Conventions on when to use "//" and "//"

A. For information that needs to be known to the caller, use the "///" comment so that the caller can see it at the time of invocation.

B. For the internal implementation details of the code, a comment that needs to be known by the maintainer, using "//". Reduce caller read time.

• Unwanted comments

Reading comments takes time to read real-world code, and each comment takes up space on the screen. So we agreed that the comments added must be meaningful comments, otherwise do not waste time and space.

The core idea of distinguishing between writing notes is not to write annotations for facts that can be inferred quickly from the code itself.

• Do not annotate for comments

Some people may have previous companies that have high requirements for annotations, such as the "when to write comments" section of the requirements. So many people annotate to write comments.

If there is no special requirement, we should forbid writing the following meaningless comment.

<summary>

The class definition for account

</summary>

public class BinaryTree

{

<summary>

Total counts of the nodes

</summary>

public int Nodescount {get; private set;}

<summary>

All the nodes in the tree

</summary>

Public list<binarynode> Nodes {get; set;}

<summary>

Insert a node to the tree

</summary>

<param name= "Node" >the node want insert into the tree</param>

Node

• Don't use annotations to whitewash bad code

One of the common motivations for writing comments is to try to make bad code visible to others. For this "cane-type comment", we do not need, we have to do is to change the code to be more "self-explanatory."

Remember: "Good code > Bad code + good comment"

As the comment of the following function

Enforce limits on the reply as stated in the request

such as the number of items returned, or total byte size,etc.

Reply

Since knowing the name of the function can be difficult to read, why not just change the name? This way all calls to this function can be quickly known about the function, without any further follow-up to see what the function does.

public void enforcelimitsfromrequestonreply (Request request,reply Reply)

• Log comments

Someone likes to add a comment at the beginning of the module each time they edit the code. Such annotations are like a log that records each modification. Long ago this kind of record was important for maintenance. But for the current source control, these records are completely redundant and need to be completely abolished.

/***************************************************

* July-29-2014:fix Bug-12345:add New method to calculate nodes Count

* July-20-2014:fix Bug-11111:add Insert new node method

*    ......

* July-20-2014:task-00001:create BinaryTree class

***************************************************/

• Personal signature

Added by XXXX

Some people think that this kind of comment helps the person who does not know the meaning of the code to discuss with him. In fact, this note is placed in that year and the next, the code and the original author wrote the source of the more and more different, and xxxx is more and more irrelevant.

Again, this kind of information can be seen in TFS, not in the code.

• Location identification

AddNodePlace1

AddNodePlace2

Someone likes to include a location identifier in the code comment to make it easier for him to find the location of the code.

The IDE now integrates these features, such as the ability to use a bookmark (ctrl+b,t) in vs.

Do not add this type of comment to your code.

• Commented-Out Code

Commenting out the code directly is a very annoying practice.

Others are afraid to erase the code. They will think that the code is still here for a reason, and that this code is important and cannot be deleted. And everyone reading the code goes to see if the commented out code has the information they need to be aware of.

These commented-out codes are stacked together, emitting a rotten stench.

• Required annotations
• Keep track of your valuable insights into your code

You should include in your code an insight note that is valuable to the code.

such as://Unexpectedly, for these data with a binary tree selects table to 40% faster

The cost of hashing is much larger than that of the left and right.

This note will tell the reader some important performance information to prevent them from making unnecessary optimizations.

• Write comments for deficiencies in the code

The code is always evolving, and there is definitely a shortage in the code.

These deficiencies should be recorded so that Yimeimei can be perfected.

If the code needs to be improved:

TODO: try to optimize the algorithm

If the code is not complete:

TODO: work with image formats other than JPG

You should always write down the idea of how the code will change in the future in a commented manner. This annotation gives the reader valuable insight into the quality of the code and the current state, and even shows them how to improve the direction of the code.

• Add comments to a predictable question

When someone reads your code, some parts of it may make them wonder: "Why do you write this?" "Your job is to annotate these parts," he added.

Such as:

Because the creation of connection is resource-intensive and time-consuming and requires multi-threaded access,

So using multithreaded singleton mode

public static Connection Instance

{

Get

{

if (_instance==null)

{

Lock (_lock)

{

if (_instance = = null)

{

_instance = new Connection ();

}

}

}

return _instance;

}

}

• To announce a possible trap

When you write a comment for a function or class, you can ask yourself, "Is there anything unexpected about this code?" Will it be useless? "。 Basically you need to plan ahead and anticipate the problems others might encounter when using your code. Such as:

XXX: Because it takes a long time to call an external mail server to send a message, use an asynchronous method call to prevent the UI from dying.

public void SendEmail (string to, string subject, String body)

• A summary comment for a block of code

A summary comment for a block of code allows the reader to get the gist of the block before going into the details, even skipping the block of code directly, so you can quickly and accurately grasp the code.

As the reader sees://The following code uses a two-point lookup algorithm to quickly find the appropriate user based on the user ID

Then he can quickly understand the logic of the code below, otherwise it will take some time to look at the two points.

Self-summarized C # Coding specification--4. Comments