En el momento en que iniciamos el desarrollo de una aplicación, haciendo uso de cualquiera de los muchos lenguajes de programación disponibles, se nos presenta una magnífica oportunidad para tratar de generar un código que sea legible y de calidad. Si no somos cuidadosos, cualquiera que herede nuestro código podría sufrir lo indecible encontrándose, en más ocasiones de las que creemos, con un código cuasi-críptico.
Aún si entramos a formar parte de un equipo de desarrollo en una fase avanzada de programación, respetar una serie de normas básicas de codificación redundará positivamente en el resultado final.
Con el tiempo han ido surgiendo multitud de recomendaciones o guías de estilo, muchas veces dirigidas a lenguajes en particular. Sin embargo no es difícil disponer o elaborar una serie de recomendaciones generales, aplicables a casi todos ellos. Por supuesto no faltan guías o recomendaciones de codificación «oficiales» de empresas como Google, Microsoft, Sun Microsystems, etc.
Estas buenas prácticas o normas de programación son un conjunto de reglas, de carácter opcional u obligatorias. Se implementan con el fin último de mejorar la calidad del software desarrollable. Podremos obtener gracias a ellas beneficios como:
- Facilitar la etapa de desarrollo para el programador o programadores
- La legibilidad y mantenibilidad del código generable mejorarán en gran medida
- Cierta clase de errores comunes podrán ser evitados de inicio
Si bien en el presente documento nos centraremos en normas o reglas de aplicación para C/C++, serán extensibles con facilidad a muchos otros lenguajes, como pudieran ser Java, C#, etc. Hay que tener en cuenta que para cada lenguaje de programación existen distintos estándares y conjuntos de buenas prácticas. Para el caso particular del lenguaje C, destacaríamos dos estilos principales:
- Estilo GNU, popularizado por Richard Stallman y que forma parte de los “GNU Coding Standards” utilizados en el proyecto GNU.
- El estilo K&R, el cual es el estilo original de programación en C, utilizado por Kernighan y Ritchie.
Con independencia de cuántos y variados estilos o guías existan, usted como desarrollador debería adaptar un estilo propio y seguirlo de forma consistente. Para facilitarle esta etapa de creación y adaptación de estilo, describiré una serie de prácticas “obligatorias” que debería poder seguir con facilidad.
Estructura del programa
- El código deberá presentarse indentado dentro de cada estructura de control, como pueden ser los bloques if, for, while, etc., y también para el contenido de funciones, registros, constructores, etc. De este modo logramos resaltar de forma visual una estructura lógica del código, lo cual simplifica enormemente su lectura. Por ejemplo:
- Siempre utilice llaves en todas las estructuras de control, aún incluso si sólo tienen 1 instrucción en su interior. Con esto se evitarán posibles errores si, posteriormente, deseamos añadir más instrucciones bajo la estructura de control afectada. La única excepción aceptable a esta regla es cuando ponemos la instrucción a ejecutar en la misma línea que la instrucción de control, como por ejemplo:
- Deberemos usar de forma consistente un estilo de apertura y cierre de llaves, como pueden ser los siguientes:
- No se escribirá código justo después de una llave de apertura.
- Sólo se insertará una instrucción por línea.
- Deberá emplearse un espacio después de las comas, por ejemplo:
- Usaremos paréntesis para especificar el orden de prioridades en operaciones aritméticas complejas, evitando que el programador deba recordar todas las reglas de precedencia de operadores. La única excepción aceptable es para los índices de los arreglos, como por ejemplo:
miarray [i + 1];
- Separaremos los operadores binarios con espacios a ambos lados, ya que de este modo se resalta el operador y se facilita la lectura del programa. Por ejemplo:
- Deberemos decantarnos desde el principio entre utilizar o no espacios antes de cada llamada a función y uso de una estructura de control, como por ejemplo:
- Deberemos evitar especialmente el uso de instrucciones que no se ejecuten nunca, como por ejemplo:
- Siempre terminaremos con una instrucción break para finalizar un bucle de iteración, en vez de modificar la propia variable de iteración.
- Toda instrucción switch deberá disponer de un caso default, siendo éste el último caso
Variables y usos
- Como norma general, nunca debemos usar variables globales.
- Las variables usadas como índices en iteraciones serán la i, j, k… típicamente darán comienzo en la i.
- Su nombrado deberá dar una idea del uso que se le dará a la variable.
- Es recomendable usar un formato camelCase para el caso de variables de nombre compuesto. De esta forma, si tenemos una variable que almacenará el resultado de una suma, podría llamarse con formato camelCase como sumaDigitos por ejemplo.
- Los valores constantes deberán declararse al comienzo del programa usando #define y su nombre deberá escribirse en mayúsculas.
- Toda variable debería iniciarse con algún valor en su declaración.
- Para el caso de variables tipo puntero, siempre deberán inicializarse a NULL.
Sobre los comentarios
- Todo fichero de código del programa debe comenzar con un comentario que describa su propósito, fecha de creación y modificación, motivos de las modificaciones, autor o autores, etc.
- Cada bloque de código comenzará con un bloque de comentarios propio en el que al menos se detalle su propósito, los parámetros de entrada que use, posibles valores de retorno, códigos de error o retorno que genere, etc. La parte de los parámetros de entrada y salida estarán bien separados.
- Es muy importante actualizar los comentarios de cada bloque de código que modifiquemos, siendo una cuestión prioritaria.
- Incluiremos un espacio en blanco después de la apertura del bloque de comentarios y antes del cierre.
- En caso de referirnos a una variable dentro del bloque de comentarios, usaremos comillas simples. Por ejemplo: /* La variable ’sumaItems’ representa el sumatorio total de ‘Items’ en el array */
- Para el caso de comentarios multi-línea, haremos como en el siguiente ejemplo:
- Cada bloque de comentario se refiere al código que le precede inmediatamente y por ello compartirá su mismo nivel de indentación.
- Deberemos separar los párrafos dentro de un bloque de comentarios con una línea en blanco, como por ejemplo:
- Por último, no escribiremos comentarios para obviedades, como por ejemplo indicar que un índice i dentro de un iterador se usará para esto mismo, pues además de evidente es lo que todo el mundo esperaría. En caso de duda, es preferible optar por escribir más comentarios y no menos.
Analista programador en activo desde el 2001 usando lenguajes variados (Clipper, Pascal, Delphi, ensamblador, Visual Basic, C/C++, Java …) y actualmente Angular y VueJS para aplicaciones web FrontEnd.