Discussion on the programming style 3

Third, the annotation specification:

1, the function header annotation

For functions, you should comment on the following format from the features, parameters, return values, main ideas, call methods, date six aspects:

Program Description Start

//================================================================//

Function: Deletes another string from one string.

Parameters: Strbydelete,strtodelete

(entry) Strbydelete: Deleted string (original String)

(exit) Strtodelete: A string to be removed from the previous string.

Return: Find and delete return 1, otherwise return 0. (Error encoding to//list of error codes for the return value).

Main idea: This algorithm mainly uses the method of cyclic comparison to find out from the Strbydelete

A string matched to the strtodelete and matched to multiple strbydelete

There are multiple strtodelete substrings in the case not handled. Please see:

Title......

Call Method: ...

Date: Start date, such as: 2000/8/21.9:40--2000/8/23.21:45

//================================================================//

Function name (...)

End of Program Description

①, for some functions, some of its parameters are incoming values, while some of the parameters are outgoing values, it is important to specify whether the parameter is an entry parameter or an exit parameter, and for some ambiguous arguments (for example, to indicate that the angle parameter is in radians (PI) when the argument is an angle). or in degrees, for both the import and export variables should be at the entrance and exit at the same time marked. Wait a minute.

②, function annotations should be placed in the header file of the function, and the implementation part of the function in the implementation file should place the annotation at the same time.

③, in the comments should be detailed description of the function of the main implementation of ideas, especially to indicate some of their own ideas, if necessary, should specify the reason for the idea. You should comment on the origin of the function for some of the imitated functions.

④, in the annotation in detail to indicate the function of the appropriate call method, for the return value of the processing methods. In the comments you want to emphasize the danger aspect of the call, where it can go wrong.

⑤, a comment on a date requires a record of the date from the beginning of the write function to the test of the end function.

⑥, there should be a set of special strings to be identified between the start of a function comment and the function name.

If the algorithm is more complex, or the variable definition in the algorithm is relative to the location, the definition of the variable is required to be illustrated. The incomprehensible algorithm can be illustrated as much as possible.

2, the variable annotation:

The comment for a variable describes the role of the variable immediately after the variable. In principle for each variable should be commented, but for very obvious variables, such as: I,j and other cyclic variables can not be annotated.

Example: The number of roots of a long llinecount//line.