Estas convenciones han sido definidas para ser aplicadas de forma transversal en los distintos lenguajes utilizados dentro del proyecto. Sin embargo, su implementación puede variar en función del lenguaje y del paradigma de programación.
Propósito
Mantener un estilo uniforme en todos los archivos y módulos, de modo que el formato del código facilite su lectura, comprensión y mantenimiento a lo largo del desarrollo.
Convenciones
Indentación
- Usar espacios, no tabulaciones (tabs).
- La cantidad de espacios puede variar según el lenguaje, pero debe mantenerse uniforme dentro de cada archivo.
- Se debe seguir el estilo si es aplicable según la guía de estilos de Google.
Longitud de línea
- Límite recomendado: 100 caracteres por línea.
- Límite máximo: 120 caracteres.
- Si se supera el límite, dividir la línea de forma lógica, sin afectar la legibilidad.
Líneas en blanco
- Usar una línea en blanco para separar bloques lógicos.
- Evitar líneas en blanco múltiples consecutivas.
Llaves y delimitadores
- Usar delimitadores explícitos cuando el lenguaje lo permita o lo requiera, esto es, llaves, corchetes y paréntesis.
- La ubicación de los delimitadores debe seguir el estilo definido en la guía oficial del lenguaje.
- Evitar colocar múltiples instrucciones en una misma línea.
Espaciado
- Incluir espacios:
- Después de comas delimitadoras (por ejemplo, en argumentos de funciones).
- Alrededor de operadores (
=
,+
,-
, etc.) en asignaciones simples.
- No incluir espacio en definiciones de constantes o argumentos por nombre.
- Incluir espacio después de palabras clave como
if
,for
,while
,switch
,catch
, antes del paréntesis. - Evitar espacios innecesarios dentro de llamadas a funciones, paréntesis o estructuras de control.
Comentarios
- Alinear los comentarios con la indentación del bloque que documentan.
- Colocar comentarios breves encima del bloque de código, no al final de la línea.
- Comentarios extensos deben presentarse como bloques estructurados.
- Cada función o clase debe tener comentarios en formato docstring.
Estructura
Cuando sea compatible con el lenguaje, se recomienda el siguiente orden en los archivos fuente:
- Encabezado de documentación (propósito del archivo)
- Importaciones o dependencias
- Declaración de constantes globales (si aplica)
- Definición de clases, funciones o componentes
- Código ejecutable (si aplica)
- Exportaciones o exposición del módulo (si aplica)
Errores comunes
Ejemplo | Motivo de rechazo |
---|---|
if (x) return; |
Omitir las llaves en estructuras condicionales afecta la legibilidad y aumenta errores. |
Uso de tabs | Genera inconsistencias visuales. En Python, puede causar errores en tiempo de ejecución. |
Líneas demasiado largas | Dificultan la lectura y complican ver los cambios en el historial. |
Comentarios al final de línea | Afectan la legibilidad. |
Espacio inconsistente | Rompe la uniformidad visual. |
Ejemplos
Ejemplo de formato correcto (pseudo-código)
// Calcula el doble de un número dado
// Simulación de importación (como placeholder)
import * as math_utils from './math_utils.js'; // si existe un módulo externo
// Constantes globales
const FACTOR = 2;
// Función principal
function getProduct(number, factor = FACTOR) {
return number * factor;
}
// Código ejecutable
const result = getProduct(4);
const other_result = getProduct(4, 6);
console.log(result);
console.log(other_result);
// Exportación del módulo
export { getProduct };
Aplicación conforme al lenguaje
Las guías de estilo establecidas en la sección Guías oficiales de estilo han sido adoptadas como referencia obligatoria dentro del Estándar Básico de Codificación del proyecto SIGIC. En todos los casos donde una convención sugerida en esta sección no sea aplicable, se deberá seguir la convención correspondiente de la guía oficial del lenguaje.
⚠ IMPORTANTE
En caso de conflicto entre una convención sugerida y una convención oficial del lenguaje, prevalecerá lo definido por la guía de estilo.