software programming specification Learning (2)-Comment

 software programming specification Learning (2) -- Comment

2-1: Generally, the valid comments of the source program must be20%Above

Note:The principle is to help read and understand the program, Added to the place where the comment is added. The comment language must be accurate, easy to understand, and concise.

2-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. filename: // file name Author: Version: Date: // author, version, and completion date Description: // describes the main functions completed by this program file, others: // description of other content functionlist: // main function list. Each record should include the function name and brief description of the function. 1 ..... history: // modify the history list. Each modification record should include the modification date, modification // author, and modification description 1. date: Author: modification: 2 .... **************************************** *********/

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 functionlist: // main function and its function 1. ------- history: // historical 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.

2-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), etc.

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: // function, performance, and other descriptions CILS: // list of functions called by this function calledby: // tableaccessed: // The accessed table (this item is only for the program involved in the database operation) tableupdated: // The modified table (this item is only for the program involved in the database operation) input: // input parameter description, including the operation and use of each parameter, value description, and relationship between parameters. Output: // description of the output parameters. Return: // description of the function return value others: // other instructions ************************************ *************/

2-5: Write and annotate the code, modify the code, and modify the corresponding comments to ensure the consistency between the comments and the code. Delete comments that are no longer useful

2-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.

2-7: Avoid using abbreviations in comments.

Note: before or after the abbreviation is used, you must describe the abbreviation.

2-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

Example: The following example is invalid.

repssn_ind = ssn_data[index].repssn_index;repssn_ni = ssn_data[index].ni;/* get replicate subsystem index and net indicator */

Should be written as follows

/* get replicate subsystem index and net indicator */repssn_ind =ssn_data[index].repssn_index;repssn_ni =ssn_data[index].ni;

2-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 above adjacent positions or on the right

Example:

/* active statistictask number */#defineMAX_ACT_TASK_NUMBER 1000#defineMAX_ACT_TASK_NUMBER 1000 /* active statistic task number */

2-10: Data Structure Declaration (including arrays, structures, classes, enumeration, etc.). If the name is not fully self-Annotated, it must be annotated. Comment on the data structure should be placed in the adjacent position above it and cannot be placed below; 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 interfacewith 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*/};

2-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 whensccp translate * // * Global titlefailure, as follows * // Variable Function and description/* 0-Success 1-GT table Error * // * 2-GT error others-No use * // variable value range/ * Only function sccptranslate () in * // * This modual canmodify it, and other * // * module can visitit through call * // * The functiongetgttranserrorcode () * // use byte g_gttranerrorcode;

2-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.

Example: In the following example, the layout is not neat and reading is inconvenient.

void example_fun(void ){/* code one comments*/   CodeBlock One        /* code two comments */   CodeBlock Two}

The layout should be changed as follows.

void example_fun(void ){    /*code one comments */   CodeBlock One    /*code two comments */   CodeBlock Two}

2-13: separate comments from the code above with blank lines

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

/* code one comments*/program code one/* code two comments*/program code two

Should be written as follows

/* code one comments*/program code one/* code two comments*/program code two

2-14: The variable definition and branch statements (condition branches, loop statements, etc.) must be annotated

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.

2-15: For the case statement 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 processing and the next case statement.

Note: This makes it clear the intention of the programmer and effectively prevents missing break statements for no reason.

Example (note the italic bold part ):

caseCMD_UP:     ProcessUp();   break;case CMD_DOWN:    ProcessDown();   break;case CMD_FWD:    ProcessFwd();   if (...)   {        ...        break;   }   else   {       ProcessCFW_B();   // now jump into case CMD_A   }caseCMD_A:      ProcessA();      break;caseCMD_B:      ProcessB();      break;case CMD_C:      ProcessC();       break;caseCMD_D:      ProcessD();      break;...

Others

2-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-2: The Code becomes self-Annotated by correctly naming functions, processes, variables, and structures, and reasonably organizing the code structure.

Note: clear and accurate names of functions and variables can increase code readability and reduce unnecessary comments.

2-3: Comments code functions and intentions 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.

Example: The following annotations are of little significance.

/* if receive_flag isTRUE */if (receive_flag)

The following comments provide additional useful information.

/* if mtp receive amessage from links */if (receive_flag)

2-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.

Example: See the following example.

If (...) {// program code while (index <max_index) {// program code}/* end of while (index <max_index) * /// specify the end Of the while statement}/* end of IF (...) * /// specify which if statement ends

2-5: The comment format should be as uniform as possible. We recommend that you use "/*…… */"

2-6: Comments should take into account the ease of reading and appearance of the program layout. If the language used is both Chinese and English, it is recommended to use more Chinese unless it can be expressed in a very 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.