Cuestiones de estilo

Introducción¶

Este documento establece un conjunto de reglas de estilo, diseñadas para que su código en C sea más claro, legible y menos propenso a errores. La programación en C ofrece una gran flexibilidad, pero ello también facilita la adopción de malas prácticas que pueden conducir a errores de difícil detección. Por este motivo, la adhesión a un conjunto de reglas claras es fundamental para mantener el código ordenado y seguro.

La idea detrás de estas reglas es que un código de calidad no solo debe ser funcional, sino también comprensible para cualquier profesional que deba leerlo, ya sea vos mismo en el futuro o un colega que se incorpore al proyecto. Un código limpio y bien organizará facilita la colaboración, ahorra tiempo en la fase de corrección y previene complicaciones durante la depuración o actualización del software.

Estas reglas abarcan desde la nomenclatura de variables y funciones hasta la estructuración de condicionales y lazos. Su observancia no solo contribuye a la coherencia del proyecto, sino que también resulta en un código más robusto y mantenible a largo plazo.

Al comenzar, la aplicación de reglas estrictas en un lenguaje flexible como C te proporciona un marco sólido. A medida que tu comprensión del lenguaje se profundice, podés adaptar estas reglas para desarrollar un estilo propio.

Apertura a Sugerencias y Debate¶

Estamos abiertos a debatir todas las reglas. Para ello, solo tenés que abrir un hilo en Discussions o un ticket en el Issue Tracker. Aceptamos propuestas de nuevas reglas, clasificaciones, explicaciones y potenciales excepciones.

Principios Clave¶

• Claridad: El código debe ser fácil de leer.

• Mantenibilidad: Debe ser sencillo de modificar y extender.

• Consistencia: El uso de un estilo uniforme optimiza la colaboración.

• Eficiencia: Se debe optimizar el rendimiento sin sacrificar la legibilidad.

Estructura de Clasificación de Reglas (Máscara de Bits)¶

Para facilitar la referencia cruzada y el análisis estático de las pautas de estilo, las reglas se encuentran organizadas en secciones temáticas progresivas bajo un esquema de máscara de bits de 16 bits (0xXXXX):

1. Sintaxis Básica y Nomenclatura (0x00XX): Reglas visuales, espaciado, indentación y pautas de nombrado de variables y constantes.

2. Estructuras de Control y Lazos (0x10XX): Bloques condicionales, estructuras de iteración y flujos de ejecución de sentencias.

3. Funciones y Modularización (0x20XX): Diseño de interfaces de funciones, documentación de contratos, alcance y responsabilidades.

4. Punteros y Gestión de Memoria (0x30XX): Uso de indirecciones, alocación en el heap, gestión de punteros nulos y liberación segura de recursos.

5. Gestión de Archivos y Errores (0x40XX): Apertura/cierre de flujos de archivos, validación de E/S, gestión de errno y diagnóstico del sistema.

6. Compilación y Buenas Prácticas de Ingeniería (0x50XX): Configuración de alertas, guardas de cabeceras, robustez y estructuras de código estándar.

Sintaxis Básica y Nomenclatura¶

• Sintaxis Básica y Nomenclatura (0x00XX)

  • Regla 0x0000h: La claridad y prolijidad son de máxima importancia

  • Regla 0x0001h: Los identificadores deben ser descriptivos

  • Regla 0x0002h: Una declaración de variable por línea

  • Regla 0x0003h: Siempre debés inicializar las variables a un valor conocido

  • Regla 0x0004h: Un espacio antes y después de cada operador binario

  • Regla 0x0005h: Cada bloque debe tener una indentación de cuatro espacios respecto a su contenedor y llaves

  • Regla 0x0006h: El asterisco de los punteros debe declararse junto al identificador

  • Regla 0x0007h: Los argumentos de función y las variables locales deben usar snake_case en minúsculas

  • Regla 0x0008h: Las constantes (const o #define) deben nombrarse en MAYUSCULAS_SNAKE_CASE

  • Regla 0x0009h: Las líneas de código no deben exceder los 79 caracteres

  • Regla 0x000Ah: Escribí comentarios que expliquen el “porqué”, no el “qué”

Estructuras de Control y Lazos¶

• Estructuras de Control y Lazos (0x10XX)

  • Regla 0x1001h: Todas las estructuras de control deben utilizar llaves

  • Regla 0x1002h: Evitá el uso descontrolado de break y continue; preferí lazos con bandera de control

  • Regla 0x1003h: Utilizá el lazo for para iteraciones con rango o contador definido y while para lazos controlados por condiciones lógicas

  • Regla 0x1004h: Las condiciones complejas deben ser simplificadas o comentadas

  • Regla 0x1005h: Evitá las condiciones ambiguas basadas en la “veracidad” (truthiness) del tipo de dato

  • Regla 0x1006h: No utilizar la instrucción goto

  • Regla 0x1007h: No utilizar el operador condicional (ternario) ?:

  • Regla 0x1008h: Toda instrucción switch debe incluir un caso default

Funciones y Modularización¶

• Funciones y Modularización (0x20XX)

  • Regla 0x2001h: Las funciones deben usar cláusulas de guarda y retornos anticipados para evitar la anidación profunda

  • Regla 0x2002h: Las funciones no deben contener printf o scanf, a menos que ese sea su propósito explícito

  • Regla 0x2003h: Todas las funciones deben incluir documentación completa y estructurada

  • Regla 0x2004h: No se permite el uso de variables globales

  • Regla 0x2005h: Cada función debe tener una única responsabilidad (Principio de Responsabilidad Única)

  • Regla 0x2006h: Una aserción por cada función de prueba

  • Regla 0x2007h: Mantené el alcance de las variables al mínimo posible

  • Regla 0x2008h: Los valores de retorno numéricos deben definirse como constantes de preprocesador o enums

  • Regla 0x2009h: Los ejercicios deben ser resueltos mediante funciones

  • Regla 0x200Ah: Los nombres de funciones y procedimientos deben usar snake_case en minúsculas

Punteros y Gestión de Memoria¶

• Punteros y Gestión de Memoria (0x30XX)

  • Regla 0x3001h: Siempre verificá la asignación exitosa de memoria dinámica

  • Regla 0x3002h: Liberá siempre la memoria dinámica y asigná NULL al puntero para evitar punteros colgantes

  • Regla 0x3003h: No mezcles operaciones de asignación y comparación en una sola línea

  • Regla 0x3004h: Utilizá typedef para definir tipos de estructuras con el sufijo _t

  • Regla 0x3005h: Minimizá el uso de múltiples niveles de indirección (punteros a punteros)

  • Regla 0x3006h: Documentá la propiedad de los recursos al utilizar punteros

  • Regla 0x3007h: Los argumentos de tipo puntero deben ser const siempre que la función no los modifique

  • Regla 0x3008h: Los punteros nulos deben ser inicializados y comparados con NULL, no con 0

  • Regla 0x3009h: Documentá explícitamente los casos en que una función puede retornar NULL

  • Regla 0x300Ah: Utilizá cast explícito al convertir tipos de punteros

  • Regla 0x300Bh: Usá siempre sizeof en las asignaciones de memoria dinámica, prefiriendo sizeof(*ptr)

  • Regla 0x300Ch: Verificá siempre los límites de los arreglos antes de acceder a sus elementos

  • Regla 0x300Dh: Utilizá enum en lugar de “números mágicos” para conjuntos de estados y valores constantes

  • Regla 0x300Eh: Documentá explícitamente el comportamiento de las funciones al manejar punteros nulos como argumentos

  • Regla 0x300Fh: Liberá la memoria en el orden inverso a su asignación

  • Regla 0x3010h: Las variables que representan tamaños o índices de arreglos deben ser de tipo size_t

  • Regla 0x3011h: Si una función recibe un puntero genérico para operaciones de solo lectura, la firma de la función debe utilizar const void*

  • Regla 0x0035h: Diseñá los Tipos de Datos Abstractos utilizando punteros opacos

  • Regla 0x0036h: Asigná NULL al puntero tras liberar un recurso opaco en el ámbito del cliente

Gestión de Archivos y Errores¶

• Gestión de Archivos y Errores (0x40XX)

  • Regla 0x4001h: Manejá correctamente la apertura y cierre de archivos

  • Regla 0x4002h: Validá los retornos de las operaciones de lectura y escritura de archivos

  • Regla 0x4003h: Utilizá errno, perror y strerror para reportar fallos del sistema operativo de manera precisa

  • Regla 0x4004h: Asegurá la simetría de recursos al abrir y cerrar archivos en el mismo nivel de abstracción

  • Regla 0x4005h: Evitá el uso de offsets y posiciones fijas codificadas a mano en archivos binarios sin validar sus dimensiones

Compilación y Buenas Prácticas de Ingeniería¶

• Compilación y Buenas Prácticas de Ingeniería (0x50XX)

  • Regla 0x5001h: Los arreglos estáticos deben ser creados con un tamaño fijo en tiempo de compilación

  • Regla 0x5002h: Desarrollá y compilá siempre con todas las advertencias del compilador activadas

  • Regla 0x5003h: Utilizá guardas de inclusión en todos los archivos de cabecera

  • Regla 0x5004h: Todas las operaciones con cadenas deben ser seguras

  • Regla 0x5005h: Organizá la estructura de tus archivos .c de forma estándar

  • Regla 0x5006h: Preferí fgets sobre gets y scanf para leer cadenas