C ++ coding specification (1): code annotation

Document directory

• 6. Todo comments

C ++ coding specification (1): code annotation

C ++ coding specification (2): naming convention

 

When you read other people's code without comments, it would be quite painful. when it comes to annotations, we immediately think of adding some descriptive information through // or. this is only a narrow comment.

In the broad sense, we can understand that any information that helps to understand the code can be considered as a comment.

We can compare code writing with writing articles. natural languages have lexical, syntactic, and semantic concepts. the syntax and syntax in the Code are equivalent to the basic syntax specification in a programming language. this is what we must master when learning a programming language. therefore, this information is not involved in comments.

Annotations mainly involve semantic descriptions. in terms of semantics, software products are oriented to applications, namely the logic of the problem to be solved. For some application software, it can also be called business logic. after clarifying the business logic, we will discuss data modeling and so on. then write design documents and so on. What are the summary design and detailed design? These documents can be considered as very important notes.

The comments written to the Code are identified by // or. there is also a kind of annotation called self-annotation, that is, some useful information is obtained through the function or variable name.

 

Here we will mainly talk about comments made with // or /**/.

Use // or/**/to check whether your website is correct. The most important thing is to maintain consistency.In a project, you can reach an agreement on which one is used or used in a certain place // and /**/

 

Comment location and Common Content

 

1. File comment

C ++ code is distributed in header files and source files. If vs is used, it is an H suffix file and a CPP suffix file. of course, sometimes you use inline functions, there may be INL files. you can add comments to the beginning of each file.

The content is generally: copyright, author, write date, function description. For example:

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

Copyright: mycompany

Author: Arwen

Date: 2013-01-09

Description: Provide functions to connect Oracle

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

Or

// Copyright: mycompany

// Author: Arwen

// Date: 2013-01-09

// Description: Provide functions to connect Oracle

 

Sometimes, if you modify the code, you can also add the modifier, date, and content with the purpose of this information.

 

2. Class Annotation

It is generally a simple description of the function of this class. If you have already described the function at the beginning of the file, you can also omit it. If you want to comment it, you can simply describe it.

// Coledataobject -- simple wrapper for idataobject

Class coledataobject
{

}

Or

/* Coledataobject -- simple wrapper for idataobject */

 

3. Function comments

Describes functions and parameters of a function. For example

// Summary: connect the database

// Parameters:

// Conninfo: A class contains the connect info, such as user name, PWD, etc.

// DirectConnect: Use TNS name or use direct connection info

// Return: True is connect successfully.

Bool connectdatabase (connectinfo conninfo, bool DirectConnect );

 

Or

/*

* Summary: connect the database

* Parameters:

* Conninfo: A class contains the connect info, such as user name, PWD, etc .*

* DirectConnect: Use TNS name or use direct connection info

* Return: True is connect successfully.

*/

 

 

4. Variable comments

If the meaning of a variable is not easy to see from the variable name, and it is very important, it is best to add some notes. For example

Uint m_ngrowby; // Number of cache elements to grow by for new allocs

Or

Uint m_ngrowby;/* Number of cache elements to grow by for new allocs */

 

5. Implementation notes

Add comments before some logic code blocks that are difficult to understand. Especially for some algorithms, it looks like a few lines, but you may not understand what it means for half a day.

For example

// Copy elements into the empty space
While (ncount --)
M_pdata [nindex ++] = newelement;

In addition, if you want to annotate some parameters of a function, you 'd better write the parameters in several lines.

Void myfunction (string name, // This is my name

Int age)

 

In addition, sometimes a function is very long and contains multiple braces {}. In this case, sometimes you don't know who corresponds to the function. If you want to insert code into the function, it will be prone to errors. you can also add a comment in the braces to indicate the end of the IF or while statement.

In C #, you can use # region plus # endregion for comments. At the same time, the development environment vs can provide support for you to easily collapse such annotated code.

Vs also supports # pragma region and # pragma endregion in C ++
It is not recognized in other compilers, so it is best to use different compilers if you consider cross-platform computing or use different compilers.

 

6. Todo comments

Todo means something to be done. for example, if your code is half written, then you get off work. to help you quickly find the specific location the next day, or prevent you from forgetting it. you can use todo to comment out. some development environments provide support for it, so that you can easily find the places where todo annotations are used to serve as bookmarks. select View --> task list, and select comments from the drop-down list below to list all todo comments.

In addition, you can also write a todo file to implement the function. You can write your name and email address in the comments, and then describe the function to be implemented or other things.