C language programming specifications-notes

 

Rules:

 

1: Generally, the valid comments of the source program must be more than 20%. Note: The principle of annotation is to help you read and understand the program. It is added to the place where the annotation is added. The annotation language must be accurate, easy to understand, and concise.

 

2: Descriptive files (such as header files. h file ,. inc file ,. def file, compilation instructions file. CFG, etc.) the header should be annotated, and the notes must be listed: Copyright description, version number, generation date, author, content, functions, relationships with other files, modification logs, etc, the comment on the header file should also provide a brief description of function functions.

Example: The header comments in the following header file are standard. Of course, they are not limited to this format, but we recommend that you include the above information.

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

Copyright (C), 1988-1999, tech. co., Ltd.

File Name: // file name

Author:

Version:

Date: // author, version, and completion date

Description:

// Describes in detail the main functions completed by the program file, and interfaces with other modules or functions, control, order, independence, or dependency between output values, value ranges, definitions, and parameters

Others: // other content description

Function list: // a list of major functions. Each record should contain a brief description of the function name and function.

1 .....

History: // modify the history list. Each modification record should include the modification date and Modification

// Brief description of the user and the modification content

1. Date:

Author:

Modification:

2 ....

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

 

3: The source file header should be annotated to list: Copyright description, version number, generation date, author, module purpose/function, main functions and functions, modification log, etc.

Example: The header comments of the following source file are standard. Of course, they are not limited to this format, but we recommend that you include the above information.

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

Copyright (C), 1988-1999, tech. co., Ltd.

Filename: Test. cpp

Author:

Version:

Date:

Description: // module description

Version: // version information

Function list: // main functions and functions

1 .-------

History: // history modification record

<Author> <time> <version> <DESC>

David 96/10/12 1.0 Build this Moudle

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

Description: describes the content and functions of this file, the relationship between the internal parts, and the relationship between this file and other files. History is a list of modification history records. Each modification record should include the modification date, modifier, and brief description of the modification content.

 

4: The function header should be annotated to list: the purpose/function of the function, input parameters, output parameters, return values, call relationships (functions, tables), and so on.

Example: The comments of the following function are standard. Of course, they are not limited to this format, but we recommend that you include the above information.

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

Function: // function name

Description: // description of function functions and performance

CILS: // list of functions called by this function

Called by: // list of functions that call this function

Table accessed: // the table to be accessed (this item is only applicable to programs involving Database Operations)

Table updated: // the table to be modified (this option is only applicable to programs involving Database Operations)

Input: // input parameter description, including the role, value description, and relationship between parameters.

Output: // description of the output parameters.

Return: // description of the function return value

Others: // other instructions

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

 

5: Write and annotate the code, modify the code, and modify the corresponding comments to ensure the consistency between the comments and the code. Annotations that are no longer useful must be deleted.

 

6: The content of the comment should be clear, clear, and accurate, so as to prevent the ambiguity of the comment. Note: Incorrect comments are not helpful but harmful.

 

7: Avoid using abbreviations in comments, especially those that are very commonly abbreviated. Note: before or after the abbreviation is used, you must describe the abbreviation.

 

8: The comments should be similar to the code described. The comments to the code should be placed at the top or right side of the Code (the comments to a single statement), and should not be placed below, if it is placed above, it should be separated by blank lines with the above Code.

 

9: for all variables and constants with physical meanings, if their names are not fully self-Annotated, they must be annotated during declaration to describe their physical meanings. Comments of variables, constants, and macros should be placed in adjacent positions or the right side above them.

Example:

/* Active statistic Task Number */

# Define max_act_task_number 1000

# Define max_act_taskk_number 1000/* active statistic Task Number */

 

10: Data Structure Declaration (including array, structure, class, enumeration, etc.). If its name is not fully self-Annotated, it must be annotated. The comment on the data structure should be placed in the adjacent position above it and cannot be placed below; the comment on each field in the structure should be placed on the right side of this field.

Example: The enumerated/data/Union structure can be described as follows.

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

Enum sccp_user_primitive

{

N_unitdata_ind,/* SCCP y SCCP user unit data come */

N_notice_ind,/* SCCP policy user the No. 7 network can not */

/* Transmission this message */

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

};

 

11: global variables should be annotated in detail, including descriptions of their functions, value ranges, functions or processes to access them, and precautions for access.

Example:

/* The errorcode when SCCP translate */

/* Global title failure, as follows * // variable action and meaning

/* 0-Success 1-GT table Error */

/* 2-GT error others-No use * // variable value range

/* Only function sccptranslate () in */

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

/* Module can visit it through call */

/* The function getgttranserrorcode () * // usage

Byte g_gttranerrorcode;

 

12: The comment is scaled in the same way as the description. Note: The program can be neatly formatted and easy to read and understand.

 

13: separate comments from the code above with blank lines.

 

14: you must write comments on variable definitions and branch statements (condition branches, loop statements, etc. Note: These statements are often the key to a program to implement a specific function. For maintenance personnel, good comments help to better understand the program, sometimes better than reading the design documentation.

 

15: For case statements under the switch statement, if a case needs to be processed due to special circumstances, the next case will be processed, A clear comment must be added before the case statement is processed and the next case statement. Note: This makes it clear the intention of the programmer and effectively prevents missing break statements for no reason.

 

 

Suggestion:

 

1: Avoid inserting comments in the middle of a line of code or expression. Note: Unless necessary, comments should not be inserted in the code or expression, otherwise it is easy to make the code understandable.

 

2: The Code becomes self-Annotated by correctly naming functions, processes, variables, structures, and reasonably organizing the code structure. Note: clear and accurate names of functions and variables can increase code readability and reduce unnecessary comments.

 

3: Comments the code at the function and intent levels to provide useful and additional information. Note: The purpose of comments is to explain the purpose, functions, and methods of the Code, provide information other than the code, help readers understand the code, and prevent unnecessary repeated comments.

 

4: add a comment to the right of the block to indicate the end of a block. Note: When the code segment is long, especially when multiple nesting occurs, this can make the code clearer and easier to read.

 

5: Try to unify the comment format. We recommend that you use "/*...... */".

 

6: Comments should take into account the ease of reading and appearance of the program. If the language used is both Chinese and English, it is recommended to use more Chinese unless it can be expressed in fluent and accurate English. Note: The comment language is not uniform, and the program is easy to understand and the appearance and layout are affected. We recommend that you use Chinese for maintenance personnel's consideration.