C Language Programming Specification--------2 comments

2.1 Principles of Annotations

The purpose of the annotation is to explain the purpose, function and method of the code, provide information outside the code, help the reader understand the code, and prevent unnecessary repetition of the annotated information. Example: The following comment has little meaning.

/* If Receive_flag is TRUE */

if (Receive_flag)

The following comments give additional useful information.

/* If MTP receive a message from links */

if (Receive_flag)

2.2 descriptive file header should be commented on

Descriptive files (such as header files,. h files,. inc files,. def files, compilation documentation, CFG, etc.) should be commented in the header, which must be listed: Copyright description, version number, date of generation, author, content, function, relationship to other documents, modification log, etc. The comments in the header file should also have a brief description of the function function.

Example: The header comment of the following header file is standard, of course, not limited to this format, but the above information is recommended to be included.

/**

* Copyright (C), 1988-1999, Huawei Tech Co., Ltd.

* File name://File name

* Author:Version:Date://author, version and date of completion

* Description://For detailed description of the main functions of this program file completion, with other modules

or function interface, the output value, the range of values, the meaning and the control of the parameters

System, order, independence, or dependence

* Others://Description of other contents

* Function List://main function lists, each record should include functions name and function brief description

1 .....

* History://Modify historical list, each change record should include date of modification, modification

Description of the changes

1. Date:

Author:

Modification:

2 .....

*/

2.3 the header of the source file should be commented

The header of the source file should be commented, listed: Copyright description, version number, date of generation, author, module purpose/function, main function and function, modification log, etc.

Example: The following is the source file header comment Standard, of course, not limited to this format, but the above information is recommended to be included.

/**

* Copyright (C), 1988-1999, Huawei Tech Co., Ltd.

* FileName:test.cpp

* Author:Version:Date:

* Description://Module description

* Version://release information

* Function List://main functions and their functions

1.-------

* History://Historical revision record

<author> <time> <version > <desc>

David 96/10/12 1.0 Build this Moudle

*/

Description: Description A description of the contents of this document, function, the relationship between the internal parts of the document and other documents and other relations. History is a list of changes, each of which should include the date modified, the person who modified it, and a summary of the changes.

2.4 function Header should be commented

The function header should be commented, listing the purpose/function of the function, input parameters, output parameters, return values, call relationships (functions, tables), and so on.

Example 1: The comment comparison criteria for the following function, of course, is not limited to this format, but the above information is recommended to be included.

/**

* Function://Functions Name

* Description://Description of function function, performance, etc.

* Calls://List of functions called by this function

* Called by://List of functions that call this function

* Table Accessed://accessed tables (this item is only for programs that involve database operations)

* Table Updated://Modified tables (this item is only for programs that involve database operations)

* Input://Enter parameter description, including each parameter

Use, value description and relationship between parameters.

* Output://description of outputs parameters.

* Return://Description of function return value

* Others://Other instructions

*/

For some functions, some of the parameters are incoming values, and some of the parameters are outgoing values, so the parameters should be described in detail whether the parameter is an entry parameter, or an exit parameter, for some ambiguous parameters to do a detailed explanation (for example: when taking an angle as a parameter, to indicate whether the angle parameter is in radians (PI) or in degrees) , the variables that are both entrances and exits should be marked at both the entrance and exit points. Wait a minute.

The appropriate calling method of the function is specified in the comment, and the method of handling the return value is described in detail. In the comments, emphasize the danger aspect of the call, where there may be an error.

2.5 Considerations for commenting

(1) The proposed side write code side comments, modify the code at the same time to modify the corresponding comments to ensure that the comments and code consistency. Comments that are no longer useful are to be deleted.

(2) The contents of the note should be clear and unambiguous, meaning accurate and prevent the ambiguity of the annotation. Description: Incorrect comments are not only unhelpful but harmful.

(3) Avoid using abbreviations in annotations, especially abbreviations. The abbreviations should be described as necessary when using abbreviations or before.

(4) The comment should be similar to the code it describes, and the comments on the code should be placed either above or to the right (comments on a single statement) adjacent to the location, not below. Unless you need to, you should not insert comments in the middle of your code or expression, or you can easily make your code less understandable.

Example: The following example does not conform to the specification.

Example 1:

/* Get replicate Sub system index and NET indicator */

Repssn_ind = Ssn_data[index].repssn_index;

Repssn_ni = Ssn_data[index].ni;

Example 2:

Repssn_ind = Ssn_data[index].repssn_index;

Repssn_ni = Ssn_data[index].ni;

/* Get replicate Sub system index and NET indicator */

Should be written as follows

/* Get replicate Sub system index and NET indicator */

Repssn_ind = Ssn_data[index].repssn_index;

Repssn_ni = Ssn_data[index].ni;

(5) For all variables and constants with physical meanings, if their names are not fully self-explanatory, they must be annotated at the time of Declaration, explaining their physical meanings. The comments for variables, constants, and macros should be placed either adjacent to or to the right.

Example:

/* Active Statistic Task number */

#define Max_act_task_number 1000

#define MAX_ACT_TASK_NUMBER/* Active statistic TASK number */

(6) Data structure declaration (including array, structure, class, enumeration, etc.), if its name is not fully self-explanatory, it must be annotated. Comments on the data structure should be placed on top of each other, not below, and comments on each field in the structure are placed to the right of the field.

Example: An enumeration/data/federated structure can be described as follows.

/* SCCP interface with SCCP user Primitive message name */

Enum Sccp_user_primitive

{

N_unitdata_ind,/* SCCP notify SCCP User unit data Come */

N_notice_ind,/* SCCP notify user The No.7 network can not */

/* Transmission This message */

N_unitdata_req,/* SCCP user ' s unit data transmission request*/

};

(7) A global variable should have a more detailed comment, including a description of its function, range of values, which function or procedure to access it, and the precautions to take when accessing it.

Example:

/* The ErrorCode when SCCP translate */

/* Global Title failure, as follows *//variable action, meaning

/* 0-success 1-GT Table Error */

/* 2-GT Error others-no use *///Variable Value range

/* Function sccptranslate () in * *

/* This modual can modify it, and other */

/* Module can visit it through call * *

/* The function Getgttranserrorcode () *//use method

BYTE G_gttranerrorcode;

(8) Note and the description of the same indentation, so that the program layout neatly, and easy to read and understand the comments.

Example: The following example, typesetting is not neat, reading a little bit inconvenient.

void Example_fun (void)

{

/* Code One comments */

Codeblock One

/* Code Comments */

Codeblock

}

Should be changed to the following layout.

void Example_fun (void)

{

/* Code One comments */

Codeblock One

/* Code Comments */

Codeblock

}

(9) Separate the comment from the code above with a blank line.

Example: The following example shows that the code is too compact.

/* Code One comments */

Program Code One

/* Code Comments */

Program code

Should be written as follows

/* Code One comments */

Program Code One

/* Code Comments */

Program code

(10) The definition of variables and branching statements (conditional branching, looping statements, etc.) must be annotated. These statements are often the key to a program's implementation of a particular function, and for maintenance staff, good annotations help to better understand the program, sometimes even better than looking at a design document.

(11) For Case statements under the switch statement, if a case needs to be processed after a case is entered into the next one (i.e. no break after the previous cases), it must be preceded by an explicit comment before the cases statement is processed, In order to clearly express the intent of the program writer, effectively prevent the omission of the break statement without reason (can avoid the late maintenance staff confused: The original programmer is missing the break statement or should not have). Example:

Case Cmd_down:

Processdown ();

Break

Case CMD_FWD:

PROCESSFWD ();

if (...)

{

...

Break

} else

{

Processcfw_b (); Now jump to case cmd_a

}

Case CMD_A:

Processa ();

Break

...

(12) Add a comment marker to the right of the end line of the block to indicate the end of a block. This makes the code clearer and easier to read when the code snippet is long, especially when multiple nesting occurs. Example: See the example below.

if (...)

{

Program code

while (Index < MAX_INDEX)

{

Program code

}/* End of while (Index < MAX_INDEX) *//Indicates the end of the bar while statement

}/* End of if (...) *///Indicates which if statement ends

(13) in the sequential execution of the program, every 3-5 lines of statements, should be added a note, indicating the function of the small module composed of this paragraph. Some of the more unique ideas for yourself are required to be indicated in the notes.

(14) If the annotation format is as uniform as possible, it is recommended to use "/* ... * *".

(15) Note should take into account the procedural legibility and appearance of the factors, the use of the language, if Chinese, English, and the use of more than the English, unless it can be very fluent and accurate English expression-note language is not uniform, affecting the program legibility and appearance typesetting, for the maintenance of personnel, the proposed use of Chinese.

C Language Programming Specification--------2 comments