C # Coding specifications summarized by myself-4. Comments,

C # Coding specifications summarized by myself-4. Comments,

• Note

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.

• Annotations

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>

;}

• Method annotation Convention

/// <Summary>

/// Method description

/// </Summary>

/// <Param name = "parentNode"> parameter description </param>

/// <Returns> return value description </returns>

ParentNode)

• Comments between codes

• Conventions on when to write comments

If the customer does not have special requirements for the annotations, add the annotations as discussed below. Do not add unnecessary comments.

• Conventions for common annotation identifiers

It is agreed that the Team will frequently use several annotations and their meanings in the future:

//TODO:Something I have not handled

// FIXME: Known issues

// HACK: A Rough solution is required for a problem.

// XXX: dangerous! Important questions

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

Steps: Tools-> Options-> Environment-> Task List-> Tokens-> Add-> OK

After the configuration is complete, we can see the tasks in the code in the Comments option in the Task List (Ctrl + w, t) window.

 

 

 

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

A. Use "//" to comment out the information that the caller needs to know so that the caller can see the information during the call.

B. For the internal implementation details of the Code, the maintainer must note that "//" is used. Reduce the reading time of the caller.

• Unnecessary comments

 

Reading comments takes up time to read real code, and each comment occupies space on the screen. Therefore, we agree that the added comments must be meaningful comments; otherwise, do not waste time and space.

The core idea of the difference between writing comments is: Do not write comments for facts that can be quickly inferred from the Code itself.

• Do not comment for comments

Some companies may have high requirements on comments, such as those in the "when to write comments" section. So many people comment to write comments.

If there are no special requirements, we do not want to write the following meaningless comments.

/// <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 you want insert into the tree </param>

Node)

• Do not use comments to whitewash bad code

One of the common motivations for writing comments is to try to make bad code understandable to others. We don't need this kind of "crutches-based annotation". What we need to do is to make the code more self-explanatory ".

Remember: "Good code> bad code + good comments"

For example, 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 it is difficult to understand this function name, why not change the name directly? In this way, all the places where this function is called can quickly know the function's role, so you don't need to follow up on the function's role.

Public void EnforceLimitsFromRequestOnReply (Request request, Reply reply)

• Log Annotation

Some people like to add a comment at the beginning of the module every time they edit the code. Such annotations are like logs that record each modification. Such records long ago were significant for maintenance. However, for the current source code control, these records are completely redundant and need to be completely abolished.

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

* July-29-2014: FixBug-12345: Add new method to calculate nodes count

* July-20-2014: FixBug-11111: Add Insert new node method

*......

* July-20-2014: Task-00001: Create BinaryTree class

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

• Personal Signature

// Added By XXXX

Some people think that this annotation will help people who do not understand the meaning of this Code to discuss it. As a matter of fact, this comment has been put on that year and year. Later, the Code and the source code written by the original author are getting increasingly different, and there is no relationship with XXXX.

Again, this type of information can be seen in TFS, and should not be added to the Code.

• Location ID

// AddNodePlace1

// AddNodePlace2

Some people like to add location identifiers in code comments to help them find the location of the Code.

Currently, IDE integrates these functions. For example, you can use Bookmark (Ctrl + B, t) in ).

Do not add such comments to the code.

• Commented out code

It is annoying to comment out the Code directly.

Others do not dare to delete the code. They will think that there must be a reason for this code, and this code is very important and cannot be deleted. And everyone who reads the code will check whether there is any information they need to pay attention to in the commented-out code.

The comments of the Code will pile up together and emit a bad smell.

• Required annotations
• Record your valuable insights into the code

You should add comments of valuable insights into the code.

For example: // unexpectedly, binary trees are 40% faster than hash tables.

// The cost of hash calculation is much higher than that of left and right.

This comment will tell readers some important performance information to prevent unnecessary optimization.

• Write comments for deficiencies in the code

The code is always evolving, and there must be deficiencies in the code.

We need to record these shortcomings so that future users can complete them.

For example, when the code needs to be improved:

//TODO:Try to optimize the algorithm

For example, when the code is not completed:

//TODO:Process images other than JPG

You should record the ideas about how to change the code in the future in the form of annotations at any time. This annotation gives readers valuable insights on code quality and current status, and even shows them how to improve the code.

• Add comments to expected questions

When someone else reads your code, some of them may have the following questions: "Why do you want to write it like this? "Your job is to add comments to these parts.

For example:

// Because Connection creation consumes resources and time and requires multi-threaded access,

// Use the multi-threaded Singleton mode.

Public static Connection Instance

{

Get

{

If (_ instance = null)

{

Lock (_ lock)

{

If (_ instance = null)

{

_ Instance = new Connection ();

}

}

}

Return _ instance;

}

}

• Possible announcement traps

When writing comments 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 problems that may occur when others use your code. For example:

// XXX: it takes a long time to send an email by calling the external mail server. Please use an Asynchronous Method to prevent the UI from getting stuck.

Public void SendEmail (string to, string subject, string body)

• Comments code block summative

The summative comments of a code block allow readers to get the main idea of the code block before going deep into the details. Even sometimes, they can skip the code block directly to grasp the code quickly and accurately.

As you can see: // the following code uses the binary search algorithm to quickly find the corresponding user based on the user ID.

Then he can quickly understand the logic of the following code. Otherwise, it will take some time to look at the binary search.