Estilo y convenciones de nombres en proyectos reales

YAML es flexible, pero esa flexibilidad puede volverse un problema si cada persona escribe con su propio estilo. En proyectos grandes (microservicios, DevOps, CI/CD, Kubernetes) conviene establecer convenciones claras para mantener orden y evitar errores.

15.1 Convenciones para las claves

  • Usa siempre minúsculas.
  • Separa palabras con guion medio (-) o guion bajo (_).
  • Evita nombres largos o ambiguos.
app_name: mi-aplicacion
db_host: localhost
max_connections: 50

Evita estilos mixtos como AppName o DBHOST que dificultan la lectura.

15.2 Indentación consistente

  • Solo espacios, nunca tabs.
  • Convención más común: 2 espacios por nivel.
server:
  port: 8080
  host: localhost

Asegúrate de no mezclar 2 y 4 espacios en el mismo bloque.

15.3 Listas alineadas

Cada elemento debe comenzar con - seguido de un espacio.

frutas:
  - manzana
  - banana
  - naranja

15.4 Uso de comillas

No son obligatorias, pero se recomiendan cuando:

  • Hay caracteres especiales (:, #, {}).
  • El valor puede interpretarse como booleano (yes, no, on, off).
  • El valor comienza con ceros.
codigo_postal: "05000"
respuesta: "yes"
descripcion: "Producto: Teclado # edición limitada"

15.5 Orden lógico de las claves

En archivos extensos conviene definir un orden por secciones (configuración general, bases de datos, servicios externos, logs).

app:
  name: mi-aplicacion
  version: 1.0

database:
  host: localhost
  port: 5432
  user: admin
  password: secreto

logging:
  level:
    root: INFO
    com.miapp: DEBUG

15.6 Convenciones en proyectos DevOps

Docker Compose: nombres de servicios en minúsculas sin espacios.

services:
  web:
    image: nginx
  db:
    image: mysql

Kubernetes: metadata.name en minúsculas con guiones, labels y selectors consistentes.

metadata:
  name: mi-app-service
  labels:
    app: mi-app

15.7 Comentarios útiles

  • Explica configuraciones clave.
  • Evita comentarios triviales.
  • Coloca comentarios antes del bloque, no al final.
# Configuración de la base de datos
database:
  host: localhost
  port: 5432

15.8 Integración con linters

Para asegurar consistencia:

  • yamllint: valida sintaxis y estilo.
  • EditorConfig: define reglas de indentación.
  • Extensiones para VSCode como la de Red Hat.

15.9 Beneficios

  • Archivos más legibles y mantenibles.
  • Menos errores de interpretación.
  • Facilita la colaboración en equipo.
  • Alineado con buenas prácticas DevOps.

En síntesis, definir y seguir convenciones de estilo en YAML es clave para proyectos reales. Claves en minúsculas, listas alineadas, valores ambiguos entre comillas y una estructura ordenada minimizan errores y agilizan el trabajo en equipo.

Retornar