Normas de estilo
De ProjectFootballWiki, la enciclopedia libre.
Tabla de contenidos |
Normas de estilo para la programación en C++
Este documento es una modificación de un documento encontrado en www.procuno.com.
1 - Identación
Norma 1.1 Llaves
Se utilizaran llaves para separar los bloques de código. Se distinguiran dos tipos de bloques:
- Funciones y Clases:
Las llaves se colocaran de la siguiente forma: (incluso si el código del bloque ocupa una sola linea)
void funcion(parametros)
{
....//Codigo
}
- Bucles while, for, sentencias if, etc:
if (condicion1) {
....//Codigo
} else if(cond2) {
....//Codigo
} else {
....//Codigo
}
while (condicion) {
....//Codigo
}
Motivo:
Permite un código más compacto sin perder legibilidad, y en las funciones y clases resalta su condición diferenciadora de un simple bucle.
Norma 1.2 Espacios
Para hacer la identación se utilizaran 4 espacios, y entre un parentesis de fin de condición y una llave de principio de bloque 1 espacio. Esta norma al igual que la anterior es totalmente arbitraria, pero de esta manera no se tienen ni muchos ni pocos espacios en blanco, aparte de darle al código una mayor legibilidad.
2 - Clases y Funciones
Norma 2.1 Miembros públicos
Los datos miembros de una clase deben ser privados, ni públicos ni protegidos.
Motivo:
El declarar los datos miembros como públicos o protegidos derrota el encapsulamiento de datos que persigue el C++. Los miembros de una clase son privados en tanto no haya alguna declaración que indique lo contrario.
Norma 2.2 Identificadores de clases
Por convención los nombres clases comenzarán con C mayúscula y las variables de datos miembros de la clase comenzarán con m_ (m minúscula seguido del guión de subrayado). Esta condición para la denominación de variables miembros de la clase no excluye otras condiciones de denominación de variables de acuerdo con la norma elección de identificadores dentro de los criterios de legibilidad. Cuando se trate de una Interfaz, utilizaremos como primera letra la I mayuscula.
Motivo:
Se adoptan las convenciones para denominación de clases y miembros mas difundidos en la comunidad de programadores C++.
Norma 2.3 Funciones const
Funciones miembros de una clase que no modifiquen los datos miembros (ni llamen a funciones que los modifiquen) de la misma deben declararse constantes const.
Motivo:
De otra forma los objetos creados como constantes no tendrían acceso a las funciones miembro de la clase.
Norma 2.4 Orden de los parámetros
Los parámetros de una función se declararán en un orden consistente:
1.Parámetros de Entrada.
2.Parámetros de Entrada y Salida.
3.Parámetros de Salida.
Motivo:
Son menos frecuentes (y deseables) los parámetros de salida, por lo que el orden de esta lista es la que se espera de forma intuitiva.
Norma 2.5 Comprobar argumentos
Se debe comprobar la validez de los argumentos de entrada de la función siempre que puedan contener valores inadecuados.
Motivo:
Se intenta evitar que la función haga uso de valores fuera de rango.
Norma 2.6 Ámbito de las variables
Las variables deben declararse en el ámbito mas restringido posible.
Motivo:
Se supone que esto lleva a una utilización más eficiente de la pila. Sobretodo permite tener la declaración lo más cerca posible del uso y ayuda a evitar la declaración de variables que luego no son utilizadas. Al mantener el código no se sabe si una variable declarada pero no utilizada, lo es por error (se debía haber hecho algo que no se está haciendo) o por vaguería doméstica (el programador se olvidó de 'limpiar' su código).
Norma 2.7 Verificar asignación
Siempre que se asigne memoria de forma dinámica debe asegurarse el espacio requerido fue efectivamente servido por el sistema operativo. Nunca se debe suponer que la asignación haya tenido éxito.
Motivo:
Los errores que surgen al continuar la ejecución en caso de no disponer de memoria suelen ser fatales, son difíciles de detectar mediante pruebas y son difíciles de localizar.
Norma 2.8 Asignación de NULL
Cuando se libera memoria asignada dinámicamente, siempre se asignará nulo al puntero superviviente (aún cuando se haga de forma indirecta por otros mecanismos).
Motivo:
Esta medida, junto a la verificación de no uso de punteros nulos busca minimizar los problemas que surgen con la gestión de la memoria.
3 - Visibilidad
Norma 3.1 Uso de ficheros .h
Todos los ficheros .h incluidos en los ficheros de implementación deben serlo exclusivamente porque se usan.
Motivo:
El incluir un fichero .h sin necesidad da lugar a pensar que se intencionaba algún uso, ausente por error. Adicionalmente complica la compilación y linkado innecesariamente.
4 - Legibilidad
Norma 4.1 Número de instrucciones
No utilizar mas de una instrucción por línea.
Norma 4.2 Longitud de línea
Evitar las líneas de código de mas de 80 caracteres.
Motivo:
Incluso trabajando con pantallas gráficas, resoluciones altas y fuentes pequeñas es probable que no se puede visualizar la línea completa; lo que, además de incómodo, puede dar lugar a errores.
Norma 4.3 White Space
Debe hacerse un uso generoso de espacios y líneas en blanco. Funciones y bloques de código deben aislarse entre al menos una o dos líneas en blanco.
Motivo:
El código excesivamente compacto es difícil de leer.
Norma 4.4 Orden de ficheros .h
Los ficheros include que aparecen en la cabecera del fichero de código fuente deben organizarse en dos grupos.\\
Ficheros include estándares del sistema
Ficheros include propios del proyecto
Ambos grupos deben ordenarse alfabéticamente.
Motivo:
Permite discriminar con facilidad estructuras propias del proyecto de condiciones propias del sistema o entorno operativo.
4.5. Elección de identificadores
Norma 4.5.1 Identificadores en Castellano
Uso del Castellano excepto para aquellos términos informáticos de amplia difusión en inglés o de dificil traducción.
Motivo:
Si el objetivo de estas normas es el de favorecer la legibilidad del código, lo mejor que podemos hacer es usar nuestro lenguaje común.
Norma 4.5.2 Autoexplicativos
Todos los identificadores serán explicativos, descriptivos de la finalidad del objeto, variable, función, etc.
Motivo:
Cuanto mejor se explica el propio código menor es la necesidad de comentarlo profusamente, reduciendo así el riesgo de que los comentarios queden desactualizado en sucesivas actualizaciones.
Norma 4.5.3 Identificadores compuestos
Los identificadores compuestos se crearán usando una mayúscula para la primera letra de cada palabra que lo componga, menos la primera letra del identificador que debe ser minuscula.
Motivo:
Se pretende facilitar la lectura, en algunos casos el identificador compuesto podría tener mas de una posible descomposición.
5 - Comentarios
Norma 5.1 Minimizar
Los comentarios deben ser minimizados, deben facilitar la lectura del código y aportar información útil sobre las sentencias que afectan.
Motivo:
'Un programa oscuro debe ser mejorado, no explicado con comentarios'. Es probable que no se mantengan los comentarios tan actualizados como el código (cuanto mas si tienen poco sentido).
Norma 5.2 Estilo
Debe utilizarse la indicación de comentario propio del C++ //, en lugar del formato del lenguaje C /* */. Esta norma se refiere al código documentado, el uso de comentarios al estilo C puede ser útil para impedir la ejecución de un bloque de código en prueba, pero deben eliminarse del código definitivo.
Motivo:
Coherencia y facilidad de lectura. El comentario de C++ sólo afecta la línea actual, el de C obliga a buscar su fin en cualquier parte subsiguiente del fichero, situación que empeora si se permite anidar comentarios.
6 - Expresiones
Norma 6.1 Uso de if
Se hará uso de la palabra reservada if en lugar del operador ternario ?:
Motivo:
El operador es peculiar del C, y no presenta ninguna ventaja conocida frente a if que es mas conocido y universal y da lugar a un código mas legible.
Norma 6.2 Condiciones
Cuando se encuentren condiciones con varios && o || se pondrá la condición en varias lineas alineadas las siguientes con el comienzo de la primera condicion. Para distinguir esta situación especial, añadiremos una linea en blanco antes de empezar el código del bloque.
Ejemplo:
if( no_se_que1 &&
....no_se_que2 &&
....no_se_que3 ) {
....//Código
....//
}
Norma 6.3 Asignaciones múltiples
No deben utilizarse las asignaciones múltiples.
Motivo:
Puede dar lugar a actualizaciones erróneas, pues da a entender que ciertas variables son equivalentes (en cuyo caso sobrarían). Tampoco representa ventaja alguna en lo que se refiere al código ejecutable.
Norma 6.4 Asignaciones dentro de expresiones
Se prohibe realizar operaciones de asignación dentro de expresiones condicionales.
Motivo:
Porque dificulta la depuración y la legibilidad del código.
