Cómo completar el archivo fuente de la interfaz de acuerdo con el principio crudo se explica en forma de comentarios.

Reglas:

1: En circunstancias normales, la cantidad de comentarios efectivos en el programa fuente debe ser superior al 20%.

Nota: El principio de los comentarios es ayudar a la lectura y comprensión del programa, y ​​deben añadirse cuando sea necesario. No debe haber demasiados comentarios ni demasiado pocos. El lenguaje de los comentarios debe ser preciso, fácil de entender y conciso.

2. Los archivos descriptivos (como archivos de encabezado. h, archivos . inc, archivos . def, archivos de descripción de compilación. cfg, etc.) deben marcarse en el encabezado y las marcas deben enumerarse. : descripción de derechos de autor, número de versión, fecha de generación, autor, contenido, función, relación con otros archivos, registro de modificaciones, etc. Los comentarios del archivo de encabezado también deben incluir una breve descripción de la función.

Ejemplo: los comentarios del encabezado del siguiente archivo de encabezado son relativamente estándar. Por supuesto, no se limitan a este formato, pero se recomienda incluir la información anterior.

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

Copyright (C), 1988-1999, Tecnología. Ltd.

Nombre de archivo://Nombre de archivo

Autor:

Versión:

Fecha://Autor, versión y fecha de finalización

Descripción:// se utiliza para describir en detalle las funciones principales que completa este archivo de programa, que es diferente de otros módulos.

//Interfaz funcional, valor de salida de control, rango de valores, significado y parámetros

//Sistema, secuencia, independiente o dependiente, etc.

Otros://Otra descripción de contenido

Lista de funciones://Lista de funciones principales. Cada registro debe incluir el nombre de la función y una breve descripción de la función.

1.....

Historial://lista del historial de modificaciones. Cada registro de modificación debe incluir la fecha de modificación y la persona que realizó la modificación.

//Introducción del autor y contenido revisado

1. Fecha:

Autor:

Modificado:

2....

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

3. El encabezado del archivo fuente debe tener comentarios, que incluyan: descripción del copyright, número de versión, fecha de generación, autor, Propósito/función del módulo, función principal Sus funciones, registro de modificaciones, etc.

Ejemplo: los comentarios del encabezado de los siguientes archivos fuente son relativamente estándar. Por supuesto, no se limitan a este formato, pero se recomienda incluir la información anterior.

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

Copyright (C), 1988-1999, Tecnología. Ltd.

Nombre del archivo: test.cpp

Autor:

Versión:

Fecha:

Descripción ://Descripción del módulo

Versión://Información de la versión

Lista de funciones://Funciones principales y sus funciones

1.-

Historial://Registro de modificación del historial

& ltAuthor>& ltTime>& ltVersion>& ltdesc>

David construyó este modelo

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

Descripción: La descripción describe el contenido y la funcionalidad de este documento, las relaciones entre las partes internas y la relación entre este documento y otros documentos. El historial es una lista de registros del historial de modificaciones. Cada registro de modificación debe incluir la fecha de la modificación, la persona que la modificó y una breve descripción del contenido de la modificación.

4. El encabezado de la función debe tener comentarios, enumerando: el propósito/función de la función, parámetros de entrada, parámetros de salida, valor de retorno, relación de llamada (función, tabla), etc.

Ejemplo: Los comentarios para la siguiente función son relativamente estándar. Por supuesto, no se limitan a este formato, pero se recomienda incluir la información anterior.

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

Función://nombre de la función

Descripción://descripción de funciones, rendimiento, etc.

Llamadas: //La lista de funciones llamadas por esta función

La persona que llama://La lista de funciones que llaman a esta función

La tabla visitada: //ha accedido a la tabla (este elemento solo se usa para programas involucrados en operaciones de bases de datos)

Tabla actualizada: // Tabla modificada (este elemento solo se usa para programas involucrados en operaciones de bases de datos)

Enter://Ingrese las descripciones de los parámetros, incluida la función de cada parámetro.

//Describe el uso y los valores, así como la relación entre los parámetros.

Salida: //Descripción de los parámetros de salida.

Retorno: //Descripción del valor de retorno de la función.

Otro://Otras instrucciones

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

5. Comente mientras escribe el código, modifique el código y los comentarios correspondientes y garantice la coherencia de los comentarios y el código. . Los comentarios que ya no sean útiles deben eliminarse.

6. El contenido de las notas debe ser claro y el significado debe ser preciso para evitar ambigüedades en las mismas.

Nota: Los comentarios incorrectos no sólo son inútiles, sino también perjudiciales.

7. Evite el uso de abreviaturas en los comentarios, especialmente aquellas que no se utilizan habitualmente.

Nota: Antes de utilizar una abreviatura o abreviatura, se debe dar la explicación necesaria a la abreviatura.

8. Los comentarios deben estar cerca del código que describen. Los comentarios sobre el código deben colocarse cerca de la parte superior o a la derecha (comentarios en una sola oración), no debajo. Si se colocan arriba, deben estar separados del código anterior por una línea en blanco.

Ejemplo: El siguiente ejemplo no cumple con la especificación.

Ejemplo 1:

/*Obtener métricas del subsistema de replicación y métricas netas*/

repssn_ind = ssn_data[index]. repssn_index

repssn_ni = ssn_data[índice]. Ni;

Ejemplo 2:

repssn_ind = ssn_data[índice]. repssn_index

repssn_ni = ssn_data[índice]. Ni;

/*Obtener indicadores del subsistema de replicación e indicadores netos*/

Debería escribirse así

/*Obtener indicadores del subsistema de replicación e indicadores netos* /

repssn_ind = ssn_data[índice]. repssn_index

repssn_ni = ssn_data[índice]. NI;

9: Para todas las variables y constantes con significado físico, si sus nombres no se explican completamente por sí mismos, se deben hacer comentarios al declarar su significado físico. Los comentarios de variables, constantes y macros deben colocarse arriba o a la derecha.

Ejemplo:

/*Número de tarea de estadísticas de actividad*/

#define MAX_ACT_TASK_NUMBER 1000

# define MAX_ACT_TASK_ NÚMERO 1000/*Número de tareas de estadísticas de actividad*/

10: Declaraciones de estructuras de datos (incluyendo matrices, estructuras, clases, enumeraciones, etc.) Si sus nombres no se explican por sí solos, deben comentarse . Los comentarios sobre una estructura de datos deben colocarse encima de ella, no debajo de ella; los comentarios de cada campo de la estructura se colocan a la derecha de ese campo.

Ejemplo: La estructura de enumeración/datos/unión se puede describir de la siguiente forma.

/*interfaz sccp con nombre de mensaje básico de usuario sccp*/

Enumerar SCCP_user_primitive

{

N_UNITDATA_IND, /* sccp notifica a sccp usuario de llegada de datos de la unidad*/

N_N_NOTICE_IND, /* sccp informa al usuario que la red No. 7 no puede*/

/*Enviar este mensaje*/

N_UNITDATA_REQ, /* solicitud de transmisión de datos de la unidad de usuario sccp*/

};

11: Las variables globales deben especificarse en detalle, incluida su función y rango de valores, a qué funciones o procedimientos accede y precauciones al acceder a él.

Ejemplo:

/* Código de error durante la traducción SCCP*/

/*El título global falló, como se muestra a continuación*///La función y el significado de las variables

/* 0 - Éxito 1 - Error de tabla GT */

/* 2-error gt otros-sin uso *///Rango de valores variables

/ *Solo la función SCCPTranslate() en */

/*Este módulo puede modificarlo, otros */

/*módulos pueden acceder a él llamando a */

/*Función getgttranserrocode()*//Cómo usarlo

Byte g_GTTranErrorCode

12: los comentarios tienen sangría como se describe.

Nota: Puede hacer que el diseño del programa sea ordenado y facilitar la lectura y comprensión de los comentarios.

Ejemplo: el siguiente ejemplo no está bien escrito y es un poco incómodo de leer.

void example_fun(void)

{

/*Comentarios sobre el código uno*/

Bloque de código uno

/*Codigo dos comentarios*/

Bloque de código dos

}

Debe cambiarse al siguiente diseño.

void example_fun(void)

{

/*Comentarios sobre el código uno*/

Bloque de código uno

/*Dos comentarios en el código*/

Bloque de código dos

}

13: Utilice una línea en blanco para separar el comentario del código anterior él.

Ejemplo: El siguiente ejemplo muestra un código demasiado compacto.

/*Codificar un comentario*/

Código de programa uno

/*Código dos comentarios*/

Código de programa dos

/*Codificar dos comentarios*/

Código de programa dos

Debería escribirse así

/*Codificar un comentario*/

Código de programa uno

/*Codificar dos comentarios*/< / p>

Código de programa 2

14: Se deben escribir comentarios sobre las definiciones de variables y declaraciones de rama (ramas condicionales, declaraciones de bucle, etc.). ).

Nota: Estas declaraciones suelen ser clave para una funcionalidad específica del programa. Para los mantenedores, los buenos comentarios ayudan a comprender mejor el programa, a veces incluso mejor que leer la documentación de diseño.

15: Para la declaración de caso bajo la declaración de cambio, si un caso debe procesarse antes del siguiente debido a circunstancias especiales, se deben agregar comentarios claros antes de procesar la declaración de caso y la siguiente declaración de caso.

Nota: Esto puede aclarar la intención del programador y evitar eficazmente que la declaración de interrupción se omita sin motivo.

Ejemplo (nota negrita cursiva):

Caso CMD_UP:

ProcessUp();

Break;

Caso CMD_DOWN:

procesar abajo();

Romper;

Caso CMD_FWD:

procesar FWD();

Si(...)

{

...

romper;

}

Otro

{

proceso cfw _ B(); //Ahora salta al caso CMD_A

}

Caso CMD_A:

ProcesoA();

Romper;

Caso CMD_B:

ProcesoB();

Romper;

Caso CMD_C:

ProcesoC();

Romper;

Caso CMD_D:

ProcesoD ();

Pausa;

...

Sugerencias:

1: Evite insertar comentarios en medio de una línea de código o expresión.

Nota: A menos que sea necesario, no inserte comentarios en medio del código o las expresiones, de lo contrario, puede hacer que el código sea difícil de entender.

2. Al nombrar correctamente funciones o procedimientos, variables y estructuras, y organizar racionalmente la estructura del código, el código se explica por sí mismo.

Nota: La denominación clara y precisa de funciones y variables puede aumentar la legibilidad del código y reducir los comentarios innecesarios.

3. Anotar el código a nivel de funcionalidad e intención para proporcionar información útil y adicional.

Nota: El propósito de los comentarios es explicar el propósito, las funciones y los métodos del código, proporcionar información distinta al código, ayudar a los lectores a comprender el código y evitar la duplicación innecesaria de la información de los comentarios.

Ejemplo: El siguiente comentario tiene poco sentido.

/*Si recibir_flag es verdadero*/

if (recibir indicador)

Los siguientes comentarios proporcionan información útil adicional.

/*Si mtp recibe un mensaje del enlace*/

si (recibir bandera)

4. Agregue una marca de comentario a la derecha del final. Línea del bloque, para indicar el final del bloque.

Nota: Esto puede hacer que el código sea más claro y fácil de leer cuando la sección de código es muy larga, especialmente cuando está anidada varias veces.

Ejemplo: Vea el ejemplo a continuación.

If(...)

{

//Código de programa

while(index & lt; MAX_INDEX)

{

//Código de programa

} /*End while(index & lt; MAX _ INDEX)*////Indica el final de la declaración while.

of if end(...)*//Indica cuál termina la declaración if.

5: El formato de los comentarios debe ser lo más uniforme posible y se recomienda utilizar "/*...*/".

6. del programa y la apariencia del diseño. Si el idioma utilizado es tanto chino como inglés, se recomienda utilizar el chino con más frecuencia, a menos que puedas expresarte en un inglés muy fluido y preciso.

Nota: El lenguaje de comentarios no está unificado, lo que afecta la legibilidad y el diseño de apariencia del programa. Por el bien del personal de mantenimiento, se recomienda utilizar chino.