1 Propósito de la especificación……………………………………………………………… 3
2 Ámbito de aplicación……………………………………………………………… 3
3 Comentarios de código……………………………………………………………… 3
3.1 Convenciones de comentarios de código................................ 3
3.2 Especificaciones de anotación del encabezado del módulo.................... 3
3.3 Especificaciones de anotación del método................................. 4
3.4 Especificaciones de comentarios de línea de código................................ 6
3.5 Especificaciones de anotación variable................................. 7
4 Reglas de nomenclatura……………………………………………………………… 8
4.1 Convenciones básicas de nomenclatura................................ 8
4.2 Convenciones básicas para varios tipos de identificadores................... 9
4.3 Lista de abreviaturas de nombres de componentes.................... 10
5Otras especificaciones…………………………………………………… 11
5.1 Estilo de programación................................................ ... 11
5.2 Liberación de recursos................................................ ... 13
5.3 Manejo de errores................................................ ... 13
5.4 Otros................................................. ......... 14
1 Propósito normativo
- En el ciclo de vida de un software, el 80% del coste es mantenimiento;
- Casi ningún software es mantenido por sus desarrolladores originales durante todo su ciclo de vida;
- Los estándares de codificación pueden mejorar la legibilidad del software y permitir a los programadores comprender el código nuevo de la manera más rápida y completa posible. Para hacer cumplir las especificaciones, cada desarrollador de software debe cumplir constantemente con las especificaciones de codificación;
- La razón principal para utilizar estándares de codificación unificados es estandarizar la estructura y el estilo de codificación de la aplicación para que el código pueda leerse y comprenderse fácilmente;
- Las buenas convenciones de codificación hacen que el código fuente sea riguroso, legible y significativo, coherente con otras convenciones del lenguaje y lo más intuitivo posible.
2 Ámbito de aplicación
- Esta especificación utiliza principalmente C# como especificación del lenguaje de desarrollo y es la especificación principal del Laboratorio Bao Liang;
- Dado que esta especificación está diseñada para escribir programas, se aplica a todo el trabajo relacionado con la escritura de programas. Para cada proyecto específico, es posible que sea necesario adaptarlo y reabastecerlo.
- Productos aplicables: Programas escritos en C#.
3 comentarios de código
3.1 Convenciones de comentarios de código
- Todos los métodos y funciones deben comenzar con un comentario conciso que describa la función del código (qué hace el método). Dichas descripciones no deben incluir detalles de implementación (cómo se hace), ya que esto a menudo cambia con el tiempo y dichas descripciones pueden dar lugar a un mantenimiento innecesario de las anotaciones o, peor aún, a anotaciones incorrectas. El código en sí y los comentarios incorporados necesarios describirán el método de implementación.
- Los argumentos pasados a un procedimiento también se deben describir cuando la función del argumento no es obvia y cuando el procedimiento espera que el argumento esté dentro de un rango específico. Los valores de retorno de funciones y las variables globales que cambian los procedimientos, especialmente aquellas mediante parámetros de referencia, también deben describirse al comienzo de cada procedimiento.
3.2 Especificaciones de anotación del encabezado del módulo
Todo lo que se base en un archivo físico debe tener especificaciones de anotación de encabezado de módulo, por ejemplo: archivo .cs en C#
Descripción utilizada al comienzo de cada módulo, que incluye principalmente: ( Las palabras en negrita son partes obligatorias, el resto son opcionales)
- Nombre de archivo : El nombre de este archivo.
- Descripción de función (Descripción) : Descripción de función y descripción general del proceso de este módulo.
- Tablas de datos (Tables) : Descripción de las tablas de datos, vistas y procedimientos almacenados utilizados, si la relación es compleja se debe explicar qué tablas son borrables y cuáles son de solo lectura.
- Autor : _
- Fecha (Fecha de creación) :
- Documento de referencia (opcional): el documento de análisis y el documento de diseño correspondiente a este archivo.
- Referencia (Usando) (opcional): Cuando el sistema desarrollado hace referencia a Dlls y objetos de otros sistemas, se deben enumerar las fuentes correspondientes y si están relacionadas con el sistema (si no está seguro, puede dejarlo en blanco) para facilitar la creación de archivos de instalación.
- Historial de revisiones : Si el propietario del archivo cambia, se requiere el nombre de la persona que lo modificó, la fecha de la modificación y el motivo de la modificación.
- Separador: **************************** (tanto antes como después)
Los ejemplos son los siguientes:
3.3 Especificaciones de anotación de métodos
1> C# proporciona un mecanismo que permite a los programadores documentar su código utilizando una sintaxis de comentarios especial que contiene texto XML. En un archivo de código fuente, se pueden usar comentarios en un formato determinado para indicarle a una herramienta que genere XML en función de estos comentarios y los elementos del código fuente que los siguen. En aplicaciones específicas, las clases, interfaces, propiedades y métodos deben tener secciones <Summary>. Además, si los métodos tienen parámetros y valores de retorno, deben tener secciones <Param> y <Returns>. Los ejemplos son los siguientes:
/// <summary> /// … /// </summary> /// <param name=””></param> /// <returns></returns>
2> Los eventos no requieren anotaciones en el encabezado, pero cuando contienen procesamiento complejo (como bucles/operaciones de base de datos/lógica compleja, etc.), deben dividirse en una única función de procesamiento y el evento llama a la función.
3> Todos los métodos deben agregar comentarios de método antes de su definición.
4> Los comentarios del método utilizan el formato /// para generar automáticamente comentarios en formato de etiqueta XML.
Un diagrama de ejemplo es el siguiente:
5> Los métodos públicos en la biblioteca de clases públicas necesitan agregar el autor, la fecha y la información del registro de modificación después de los comentarios del método general. Deben estar anotados en el formato de etiquetas XML. Las etiquetas son las siguientes:
<Author>作者</Author>
<CreateDate>建立日期</CreateDate>
<RevisionHistory> --修改记录
<ModifyBy>修改作者</ModifyBy>
<ModifyDate>修改日期</ModifyDate>
<ModifyReason>修改理由</ModifyReason>
<ModifyBy>修改作者</ModifyBy>
<ModifyDate>修改日期</ModifyDate>
<ModifyReason>修改理由</ModifyReason>
<ModifyBy>修改作者</ModifyBy>
<ModifyDate>修改日期</ModifyDate>
<ModifyReason>修改理由</ModifyReason>
</RevisionHistory>
<LastModifyDate>最后修改日期</LastModifyDate>6> Si un archivo de código es escrito por una sola persona, los métodos en este archivo de código no requieren información del autor. Los autores de archivos sin código deben agregar el autor, la fecha y otros comentarios al agregar métodos a este archivo.
7> Para modificar cualquier método, debe agregar un comentario en el registro de modificación.
3.4 Especificaciones de comentarios de línea de código
1> Si el procesamiento de una determinada función requiere muchas líneas de código para su implementación y hay muchos bloques estructurales lógicos, se deben agregar comentarios antes del inicio del código para explicar las ideas de procesamiento y las precauciones para este bloque de código, etc.
2> Los comentarios se agregan en nuevas líneas y se alinean a la izquierda con el comienzo del código.
3> Las barras dobles y los comentarios están separados por espacios. La imagen de ejemplo es la siguiente:
3.5 Especificaciones de anotación variable
1> Al definir una variable, debe agregar un comentario de variable para explicar el propósito de la variable.
2> Las variables de nivel de clase deberían generar automáticamente comentarios en formato de etiqueta XML en el formato ///. El ejemplo es el siguiente:
3> Los comentarios de las variables a nivel de método se pueden colocar después de la declaración de la variable, alineados a la izquierda con los comentarios de la declaración de la variable en las líneas anteriores y siguientes, y separados del código por pestañas.
4 reglas de nomenclatura
4.1 Convenciones de nomenclatura básicas
1> Utilice un descriptor completo en inglés que pueda describir con precisión la variable/campo/clase, como nombre. Se pueden utilizar nombres simples para algunas variables con funciones obvias. Por ejemplo, la variable incremental (decreciente) en un bucle puede denominarse "i".
2> Intente utilizar terminología en los campos involucrados en el proyecto.
3> Utilice mayúsculas y minúsculas mixtas para mejorar la legibilidad del nombre. Para distinguir entre varias palabras en un identificador, escriba en mayúscula la primera letra de cada palabra en el identificador. No utilice guiones bajos como caracteres delimitadores.
Existen dos métodos de escritura adecuados para diferentes tipos de identificadores:
PasalCasing : La primera letra del identificador está en mayúscula;
camelCasing : la primera palabra del identificador está en minúscula.
4> La siguiente tabla describe las reglas de mayúsculas y minúsculas para diferentes tipos de identificadores:
5> Evite el uso de abreviaturas y, si debe usarlas, úselas con precaución. Además, se debe mantener y utilizar de forma coherente una lista de abreviaturas estándar.
6> Para abreviaturas comunes, las abreviaturas de dos letras deben estar en mayúsculas y minúsculas (ejemplo: ioStream, getIOStream); las abreviaturas de varias letras deben tener la primera letra en mayúscula y las demás letras en minúsculas (ejemplo: getHtmlTag);
7> Evite el uso de nombres largos (preferiblemente no más de 15 letras).
8> Evite el uso de nombres que sean similares o que difieran solo en mayúsculas y minúsculas.
4.2 Convenciones de nomenclatura para varios tipos de identificadores
1> Nomenclatura de ensamblaje
Nombre del laboratorio (Lab) + nombre del proyecto + nombre del módulo (opcional), por ejemplo:
Montaje del servidor central: Lab.SeverCenter;
Ensamblaje de lógica empresarial del servidor central: Lab.SeverCenter.Business;
2> Nomenclatura del espacio de nombres
Utilice el mismo método que para la denominación del ensamblaje: nombre del laboratorio (Lab) + nombre del proyecto + nombre del módulo. Además, generalmente se recomienda que el espacio de nombres y la estructura del directorio sean los mismos. Por ejemplo:
Servidor central: Lab.SeverCenter;
Control de usuarios bajo el servidor central: Lab.SeverCenter.UserControl;
Lógica empresarial del servidor central: Lab.SeverCenter.Business;
Acceso a los datos del servidor central: Lab.SeverCenter.Data;
3> Ensamblados y DLL
l En la mayoría de los casos, un ensamblado contiene toda o parte de una biblioteca reutilizable contenida dentro de una única biblioteca de vínculos dinámicos (DLL).
l Un ensamblado se puede dividir en varias DLL, pero esto es muy poco común y no se indica en esta guía.
l Los ensamblados y las DLL son la organización física de las bibliotecas, mientras que los espacios de nombres son organizaciones lógicas y su composición no debe tener nada que ver con la organización del ensamblado.
l Los espacios de nombres pueden abarcar, y a menudo lo hacen, múltiples ensamblajes. Considere el siguiente patrón para nombrar archivos DLL:
<Empresa>.<Componente>.dll
Ejemplo: Lab.SeverCenter.dll
4> Nomenclatura de clases e interfaces
l Los nombres de las clases deben utilizar sustantivos;
l Evite utilizar la abreviatura de una palabra a menos que su abreviatura ya sea bien conocida, como HTTP.
l El nombre de la interfaz debe comenzar con la letra I. Asegúrese de que el nombre de implementación estándar de la interfaz solo difiera en un prefijo "I", por ejemplo, la implementación estándar de la interfaz IComponent es Componente;
l Denominación de parámetros de tipo genérico: el nombre debe ser T o un nombre descriptivo que comience con T, por ejemplo:
Lista de clases públicas <T>
clase pública MiClase<Tsesion>
l Evite la duplicación de nombres para clases en diferentes espacios de nombres del mismo proyecto. Evite conflictos y confusión en las citas;
5> Nomenclatura de métodos
l La primera palabra suele ser un verbo;
l Si el método devuelve el valor de una variable miembro, el nombre del método generalmente es Get + el nombre de la variable miembro. Si el valor devuelto es una variable bool, generalmente se usa Is como prefijo. Además, si es necesario, considere utilizar propiedades en lugar de métodos;
l Si un método modifica el valor de una variable miembro, el nombre del método generalmente es: Conjunto + nombre de la variable miembro. Como se indicó anteriormente, considere usar propiedades en lugar de métodos.
6> Denominación de variables
l Según el alcance de uso, las variables en nuestro código básicamente tienen los siguientes tipos: variables públicas de la clase; variables privadas de la clase (protegidas y públicas); variables de parámetros del método; variables locales utilizadas dentro del método. Las reglas de denominación para estas variables son básicamente las mismas; consulte la tabla de comparación de casos de identificadores. Las diferencias son las siguientes:
a) Las variables públicas de la clase se nombran de la forma habitual, sin requisitos especiales;
b) Las variables privadas de la clase se pueden utilizar de dos maneras: con el prefijo "m", como mWorkerName;
c) La variable de parámetro del método adopta camalString, como WorkersName;
l Las variables locales dentro del método usan camalString, como WorkersName.
l No utilice _ o & como primera letra;
l Trate de utilizar palabras breves y significativas;
l Los nombres de variables de un solo carácter generalmente solo se usan para variables con una vida útil muy corta: i, j, k, m y n generalmente se usan para números enteros; c, d, e generalmente se usan para caracteres; s se usa para cadenas
l Si la variable es una colección, utilice números plurales en el nombre de la variable. Por ejemplo, el número de filas de una tabla debería denominarse: RowsCount;
l La denominación de componentes debe utilizar la nomenclatura húngara y todos los prefijos deben seguir la misma lista de abreviaturas de nombres de componentes.
4.3 Lista de abreviaturas de nombres de componentes
El principio básico de la abreviatura es tomar la primera letra de cada palabra en el nombre de la clase componente. Si solo hay una palabra, eliminar las vocales y dejar las consonantes. Las abreviaturas están todas en minúsculas.
5 otras especificaciones
5.1 Estilo de programación
1> Declaración de variables:
Para mantener mejores hábitos de lectura, no escriba varias declaraciones de variables en una línea, es decir, solo declare una variable por línea.
--Por ejemplo: String strTest1, strTest2; --Debe escribirse como: String strTest1; String strTest2;
2> Sangría de código:
l Un estilo de sangría de código consistente favorece la expresión del nivel estructural del código, lo que hace que el código sea más fácil de leer y circular;
l La sangría del código se implementa usando la tecla Tab. Es mejor no usar espacios. Para garantizar que la sangría del código sea consistente en diferentes máquinas, el ancho de la tecla Tab en C# se estipula en 4 caracteres. La interfaz es la siguiente (Herramientas - Opciones):
l Evite tener más de 5 parámetros en el método. Generalmente, 2 o 3 parámetros son apropiados. Si excede eso, debe usar una estructura para pasar múltiples parámetros.
l Para facilitar la lectura, no alargue demasiado la línea de código. El mejor ancho es el ancho de la pantalla (el ancho visible será diferente según la resolución de la pantalla). No exceda el ancho de la pantalla que está utilizando. (No más de 80 caracteres por línea de código).
l Las declaraciones Goto no deben usarse en programas.
l Siempre requiere una cláusula predeterminada en una declaración de cambio para mostrar información.
l Cuando hay más de 8 parámetros de método, se pasan en modo estructura o clase.
l Hay un espacio de medio ancho a izquierda y derecha del operador/operador
l Coloque los números {} de todos los bloques en una línea respectivamente y anídelos alineados. No los coloque en la misma línea.
3> En blanco:
l Las líneas en blanco separan segmentos de código relacionados lógicamente para mejorar la legibilidad.
l Siempre debe utilizar dos líneas en blanco en las siguientes situaciones:
a) Entre dos secciones de un archivo fuente.
b) Entre declaración de clase y declaración de interfaz.
l Siempre se debe utilizar una línea en blanco en las siguientes situaciones:
a) Entre dos métodos.
b) Entre variables locales dentro del método y la primera declaración del método.
c) Antes de un comentario de bloque (ver "5.1.1") o un comentario de una sola línea (ver "5.1.2").
d) Entre dos secciones lógicas dentro de un método para mejorar la legibilidad.
l Siempre debes usar espacios en las siguientes situaciones:
a) Se deben colocar espacios en blanco después de la coma en la lista de parámetros, como por ejemplo:
void UpdateData (int a, int b)
b) Todos los operadores binarios, excepto ".", deben estar separados de sus operandos por espacios. No debe haber espacios entre operadores unarios y operandos, como: signo negativo ("-"), incremento automático ("++") y decremento automático ("--"). Por ejemplo:
a += c + d;
d++;
c) Las expresiones en la declaración for deben estar separadas por espacios, por ejemplo:
para (expr1; expr2; expr3)
d) La transformación forzada debe ir seguida de un espacio, por ejemplo:
carácter c;
int a = 1;
c = (carbón) a;
5.2 Liberación de recursos
Todos los recursos externos deben liberarse explícitamente. Por ejemplo: objeto de conexión de base de datos, objeto IO, etc.
5.3 Manejo de errores
1> No "capte la excepción pero no haga nada". Si oculta una excepción, nunca sabrá si ocurrió o no.
2> Cuando ocurra una excepción, envíe un mensaje amigable al usuario, pero registre con precisión todos los detalles posibles del error, incluida la hora en que ocurrió, los métodos relacionados, los nombres de las clases, etc.
3> Solo detecte excepciones específicas, no excepciones generales.
Enfoque correcto:
Enfoque incorrecto:
5.4 Otros
1> Un método solo completa una tarea. No combine varias tareas en un solo método, incluso si esas tareas son muy pequeñas.
2> Utilice los tipos únicos de C# en lugar de los tipos de alias definidos en el espacio de nombres del sistema.
3> No uses valores fijos en tu programa, usa constantes en su lugar.
4> Evite el uso de muchas variables miembro. Declare variables locales y páselas a métodos. No comparta variables miembro entre métodos. Si una variable miembro se comparte entre varios métodos, será difícil saber qué método modificó su valor y cuándo.
5> No declare las variables miembro como públicas o protegidas. Todos se declaran como privados y utilizan atributos públicos/protegidos.
6> No utilice rutas específicas ni nombres de unidades en su código. Utilice rutas relativas y haga que las rutas sean programables.
7> Realice algunas "autoverificaciones" cuando se inicie la aplicación y asegúrese de que los archivos y archivos adjuntos requeridos estén en la ubicación especificada. Verifique la conexión de la base de datos si es necesario. Brinde al usuario un aviso amigable si ocurre algún problema.
8> Si no se puede encontrar el archivo de configuración requerido, la aplicación debe poder crear uno usando los valores predeterminados.
9> Si se encuentra un valor incorrecto en el archivo de configuración, la aplicación debería generar un error y mostrar un mensaje para indicarle al usuario el valor correcto.
10> Al seleccionar la columna de DataColumn, use el nombre del campo en lugar del número de índice.
Ejemplo: Columna de datos correcta["Nombre"]
Columna de datos incorrecta[0]
11> En una clase, todas las definiciones de campos se colocan al principio de la clase y delante de todos los métodos o atributos.
12> En una clase, todos los atributos se definen en un bloque de atributos:
