Las convenciones de los frameworks facilitan que las apps se entiendan sin largas docs. Aprende qué cubren, dónde fallan y cómo documentar solo las excepciones.
Las convenciones de un framework son las “formas por defecto de hacer las cosas” que un framework fomenta de forma silenciosa —o incluso espera—. En lugar de que cada equipo invente su propio layout de carpetas, esquema de nombres o flujo de peticiones/respuestas, el framework proporciona un patrón compartido. Si lo sigues, otros desarrolladores pueden predecir dónde están las cosas y cómo se comportan sin necesitar una explicación larga.
La mayoría de la documentación no se escribe porque a la gente le guste escribirla. Existe para resolver algunos problemas recurrentes:
Las convenciones abordan especialmente bien los dos primeros. Cuando ya está decidido “dónde poner X” y “cómo nombrar Y” por el framework, hay menos que explicar y menos que debatir.
“Las convenciones reemplazan la documentación” no significa que un proyecto quede sin documentación. Significa que una gran parte de la guía básica se traslada de la prosa a una estructura predecible. En lugar de leer una página de wiki para saber dónde van los controladores, lo infieres porque el framework espera controladores en cierto lugar (y las herramientas, generadores y ejemplos lo refuerzan).
El resultado es menos documentación sobre lo obvio, y más foco en documentar lo que realmente es específico del proyecto: reglas de negocio, decisiones arquitectónicas inusuales y excepciones intencionales.
Este artículo va dirigido a desarrolladores, líderes técnicos y equipos con mentalidad de producto que desean bases de código más claras y una incorporación más rápida sin mantener un sitio de documentación enorme.
Aprenderás cómo las convenciones de un framework crean “documentación implícita”, qué tipos de cosas suelen estandarizar las convenciones, dónde dejan de ayudar y qué sigue mereciendo documentación explícita—para que la claridad aumente incluso cuando los docs disminuyen.
“Convención sobre configuración” significa que un framework toma decisiones sensatas por ti—siempre que sigas sus reglas acordadas. En lugar de escribir (y leer) páginas de instrucciones de configuración, los equipos confían en valores por defecto compartidos que todos reconocen.
Piénsalo como conducir en un país donde todos acuerdan conducir por la derecha, parar en los semáforos rojos y seguir señales estándar.
Podrías escribir un manual detallado para cada intersección (“Si ves un octágono rojo, para; si la luz está verde, avanza…”), pero no lo necesitas—porque la convención ya es conocida y se aplica de forma consistente.
Las convenciones de framework funcionan igual: convierten “cómo hacemos las cosas aquí” en un comportamiento predecible.
Cuando un framework tiene valores por defecto, no hay que documentar cada pequeña decisión. El framework (y tu equipo) puede asumir patrones como:
User se mapea a los datos users)Esa base compartida reduce la documentación de “aquí están todos los pasos para configurar X” a “seguimos los valores por defecto del framework, salvo indicación contraria.” También reduce la carga mental en la incorporación: los nuevos desarrolladores pueden acertar más a menudo, porque el código coincide con lo que han visto en otros proyectos.
Las convenciones no son gratis. La desventaja es que a veces renuncias a estructuras de carpetas inusuales, nombres personalizados o flujos muy a medida.
La ventaja es la consistencia: menos debates, menos sorpresas, menos reglas de “conocimiento tribal” que solo recuerdan los veteranos. Los equipos avanzan más rápido porque dedican menos tiempo a explicar y más a construir.
Una convención solo ahorra documentación si la gente ya la conoce—o puede aprenderla una vez y reutilizarla en todas partes.
Por eso los frameworks populares son poderosos: sus convenciones se enseñan ampliamente, se usan mucho y se repiten en muchos repositorios. Cuando tu proyecto se ajusta a esos valores por defecto compartidos, tu código se vuelve entendible por defecto, con muchas menos explicaciones escritas necesarias.
Las convenciones de framework son atajos compartidos. Estandarizan las preguntas que todo nuevo compañero se hace el primer día: “¿Dónde va esto?” y “¿Cómo lo llamo?”. Cuando esas respuestas son predecibles, puedes sustituir páginas de docs por unos pocos valores por defecto consistentes.
La mayoría de frameworks empujan una estructura de proyecto reconocible: un lugar para UI, otro para rutas, otro para acceso a datos, otro para tests. Esa consistencia importa porque la gente no tiene que leer una guía para encontrar “la parte que renderiza una página” frente a “la parte que habla con la base de datos.”
Las mejores convenciones hacen que las tareas comunes parezcan memoria muscular: añade una nueva pantalla y ya sabes en qué carpeta debe ir.
Las reglas de nombrado reducen la necesidad de explicaciones como “Nuestros controladores están en X y deben enlazarse en Y.” En su lugar, los nombres implican roles.
Ejemplos comunes:
Muchos frameworks web mapean archivos a rutas (o hacen que las rutas sean fáciles de inferir). Si puedes adivinar la URL por el nombre de archivo—o viceversa—no necesitas un documento de routing para cada característica.
La convención también fija expectativas sobre rutas dinámicas, rutas anidadas y manejo de 404, así que “¿cómo añadimos un nuevo endpoint?” tiene una respuesta estándar.
Las convenciones suelen definir dónde vive el “código de datos”: modelos, repositorios, servicios, migraciones, archivos de esquema. Incluso si tu app es pequeña, tener un hogar acordado para el acceso a datos evita llamadas a la base de datos esparcidas por el código de UI.
Comandos estándar (run, test, build, lint, format) eliminan la ambigüedad. Un nuevo desarrollador no debería necesitar una página de wiki para saber cómo iniciar el proyecto—npm test (o el equivalente) debería ser la acción obvia.
Cuando estas cinco áreas son consistentes, la propia base de código responde la mayoría de las preguntas “¿cómo hacemos las cosas aquí?”.
Una wiki de “cómo funciona todo” intenta describir el sistema entero en prosa. A menudo empieza siendo útil y luego se queda desactualizada a medida que las carpetas se mueven, los nombres cambian y llegan nuevas características. Las convenciones invierten esa idea: en lugar de leer una explicación larga, lees la estructura.
Cuando un framework (y tu equipo) acuerda dónde viven las cosas, el repositorio se vuelve navegable como una cuadrícula de ciudad.
Si sabes que los componentes de UI van en components/, las vistas a nivel de página en pages/ y los handlers de API en api/, dejas de preguntar “¿dónde está X?” porque la primera suposición suele ser correcta. Incluso cuando no lo es, tu búsqueda está acotada: no está en cualquier parte, está en uno de unos pocos lugares esperados.
Las convenciones también hacen que los nombres de archivos y símbolos transmitan significado. Un recién llegado puede inferir comportamiento por ubicación y nombre:
user.controller probablemente maneja lógica de peticiónUserService probablemente contiene reglas de negociomigrations/ probablemente contiene cambios de base de datos ordenados que se ejecutan una sola vezEsa inferencia reduce las preguntas de “explícame la arquitectura” a preguntas más pequeñas y contestables (“¿Este servicio puede llamar a la base de datos directamente?”), que son mucho más fáciles de documentar.
La manera más rápida de reforzar el mapa es mediante scaffolding. Los templates iniciales y generadores crean nuevas características en la “forma correcta” por defecto—carpetas, nombres de archivo, wiring de boilerplate y a menudo tests.
Esto importa porque las convenciones solo ayudan cuando se aplican de forma consistente. Un template es una guía: incentiva que cada nueva ruta, componente o módulo tenga la estructura esperada, de modo que la base de código se mantenga legible sin añadir más páginas de wiki.
Si mantenéis scaffolds internos, enlázalos desde una página de onboarding breve (por ejemplo, /docs/getting-started) y deja que el árbol de carpetas haga el resto.
Las convenciones de framework suelen actuar como instrucciones silenciosas integradas. En lugar de escribir una página que explique “dónde van las cosas” o “cómo conectar esto”, el framework ya toma la decisión—y tu equipo aprende a leer la estructura.
Rails es famoso por convention over configuration. Un ejemplo simple: si creas un controlador llamado OrdersController, Rails asume que hay una carpeta de vistas correspondiente en app/views/orders/.
Esa única convención puede reemplazar un trozo de documentación que de otra forma explicaría:
Resultado: los nuevos compañeros pueden añadir una página siguiendo el patrón de carpetas, sin preguntar “¿dónde va este archivo?”
Django fomenta una estructura consistente de “app”. Cuando alguien ve una app de Django, espera encontrar models.py para formas de datos, views.py para manejo de peticiones y templates/ para HTML.
Podrías escribir una guía larga describiendo la anatomía de tu proyecto, pero los valores por defecto de Django ya la enseñan. Cuando un compañero quiere cambiar cómo se ve una página, sabe que debe mirar en templates/. Cuando necesita ajustar datos almacenados, empieza en models.py.
Resultado: arreglos más rápidos, menos tiempo buscando, menos mensajes de “¿qué archivo controla esto?”
Next.js reduce la documentación al hacer que el enrutamiento refleje directamente la estructura de carpetas. Crea un archivo en app/about/page.tsx (o pages/about.tsx en setups más antiguos) y automáticamente obtienes una página /about.
Eso elimina la necesidad de docs que expliquen:
Resultado: la incorporación es más simple—la gente puede descubrir la forma del sitio escaneando directorios.
Rails, Django y Next.js lucen distintos, pero el principio es idéntico: los valores por defecto compartidos convierten la estructura del proyecto en instrucciones. Cuando todos confían en las mismas convenciones, la base de código responde muchas preguntas de “¿cómo lo hacemos aquí?”—sin otro documento que mantener.
Las convenciones de un framework son “invisibles” cuando funcionan. Puedes adivinar dónde están los archivos, cómo se llaman y cómo fluye una petición por la app. La confusión vuelve cuando una base de código se desvía de esos valores por defecto compartidos.
Aparecen algunos patrones tempranos:
UserService, otra UsersManager, otra user_serviceNada de esto es automáticamente erróneo—pero significa que un nuevo compañero ya no puede confiar en el “mapa” del framework.
La mayoría de las roturas empiezan con una optimización local razonable: “Esta característica es especial, así que la colocamos aquí” o “Este nombre lee mejor.” El problema es que las excepciones son contagiosas. Una vez que la primera excepción se despliega, el siguiente desarrollador la usa como precedente:
En ese punto, la convención deja de ser convención—se convierte en conocimiento tribal.
Cuando las convenciones se difuminan, la incorporación se ralentiza porque la gente no puede predecir dónde buscar. Las tareas diarias duran más (“¿Cuál de estas carpetas es la real?”), y los errores aumentan (enlazar el módulo equivocado, usar el patrón de nombres incorrecto, duplicar lógica). Los equipos compensan con más sincronizaciones, explicaciones más largas en PRs y “docs rápidas” que se vuelven obsoletas.
Personaliza solo cuando tengas una razón clara—y deja una nota escrita.
Esa nota puede ser ligera: un comentario corto cerca de la estructura inusual, o una entrada breve en /docs/decisions que explique qué cambió, por qué merece la pena y cuál debe ser el enfoque estándar en el futuro.
Las convenciones de framework pueden eliminar páginas de explicación, pero no quitan responsabilidades. Las partes que siguen necesitando documentación son las donde tu proyecto difíe intencionadamente de lo que la mayoría de desarrolladores asumiría.
Evita re-explicar el comportamiento estándar del framework. En su lugar, captura decisiones que afectan el trabajo diario:
Ejemplo: “Usamos carpetas por feature bajo /src/features en lugar de carpetas por capa (/src/components, /src/services) porque la propiedad se mapea a equipos y reduce el acoplamiento entre equipos.” Esa sola frase evita semanas de deriva lenta.
Cuando una excepción importa localmente, pon la nota en el lugar. Un pequeño README.md dentro de una carpeta, o un comentario corto al principio de un archivo, suele ser mejor que una wiki central que nadie consulta.
Buenos candidatos:
Mantén estas notas cortas y accionables: qué es diferente, por qué lo es y qué hacer a continuación.
Ten una página ligera (a menudo en /docs/project-rules.md o el README raíz) que liste solo 5–10 elecciones clave que confunden a la gente:
Esto no es un manual completo—solo un conjunto compartido de guardarraíles.
Incluso con convenciones, la incorporación se atasca cuando la gente no puede ejecutar la app. Añade una sección corta de “Cómo ejecutar/probar” que coincida con los comandos estándar y tu configuración real.
Si el comando convencional es npm test pero tu proyecto requiere npm run test:unit, documenta eso explícitamente.
La documentación se mantiene precisa cuando se trata como parte del cambio. En las revisiones, pregunta: “¿Esto introduce una nueva excepción?” Si la respuesta es sí, exige la nota correspondiente (README local, Project Rules o quickstart raíz) en la misma pull request.
Si las convenciones son los “valores por defecto compartidos” de tu base de código, la automatización es lo que las hace reales. En lugar de pedir a cada desarrollador que recuerde reglas de una wiki, convierte las reglas en ejecutables—para que el proyecto se haga cumplir solo.
Una buena configuración detecta la deriva de forma temprana y silenciosa:
*.spec.ts, el estilo describe/it o aserciones requeridas para que las pruebas se lean de forma consistente.Estas comprobaciones reemplazan párrafos de “por favor recuerda…” por un resultado simple: el código coincide con la convención o no.
La automatización brilla porque falla pronto:
Los mejores conjuntos de reglas son pequeños y aburridos. Empieza con los valores por defecto del framework y añade solo lo que proteja la claridad (nombres, estructura y fronteras). Cada regla extra es otra cosa que la gente debe entender, así que trata las comprobaciones como código: añádelas cuando resuelvan un problema recurrente y elimínalas cuando dejen de ayudar.
Cuando una base de código sigue convenciones de framework, las pruebas pueden hacer más que “demostrar que funciona”. Pueden explicar lo que el sistema debe hacer, en lenguaje claro, junto a la implementación.
Una regla útil: una prueba debe describir un comportamiento end-to-end. Si alguien puede ojear el nombre del test y entender la promesa del sistema, has reducido la necesidad de documentación separada.
Las pruebas útiles suelen seguir un ritmo simple:
Mejor aún si el nombre refleja la intención del usuario:
signing_in_with_valid_credentials_redirects_to_dashboardcheckout_fails_when_shipping_address_is_missingEsos nombres son “documentación” que no se olvida—porque los tests fallidos fuerzan la conversación.
Los tests de aceptación son excelentes para documentar cómo se comporta el producto desde la perspectiva del usuario.
Ejemplos que pueden describir:
Estas pruebas responden “¿qué pasa cuando hago X?”—a menudo lo primero que necesita un nuevo compañero.
Los unit tests brillan cuando necesitas documentar “reglas pequeñas pero importantes”:
Son especialmente valiosos cuando la regla no es obvia por las convenciones del framework.
Los datos de ejemplo pueden ser también documentación viva. Un fixture pequeño y bien nombrado (p. ej., user_with_expired_subscription) enseña el dominio más rápido que un párrafo en una wiki.
La clave es la contención: mantener los fixtures mínimos, legibles y ligados a una sola idea, para que sigan siendo ejemplos fiables en lugar de un segundo sistema a mantener.
Los templates iniciales (y los generadores detrás de ellos) son la manera más rápida de convertir “cómo hacemos las cosas aquí” en algo que la gente realmente siga. En lugar de pedir a cada miembro que recuerde las carpetas, scripts y tooling correctos, incorporas esas decisiones en un repositorio que arranca bien.
Los tres reducen la “deuda de documentación” porque la convención está codificada en el punto de partida, no en una wiki que deriva.
En la práctica, aquí es donde herramientas como Koder.ai pueden ayudar: cuando generas una nueva app React, backend en Go, esquema de PostgreSQL o cliente Flutter desde un flujo conversacional, puedes mantener a los equipos en un “camino dorado” haciendo que la salida por defecto coincida con tus convenciones (y luego exportando el código fuente al repo).
La mayor confusión en la incorporación no suele ser la lógica de negocio, sino dónde están las cosas y cómo ejecutarlas. Un buen template hace que las tareas comunes sean idénticas entre repos: mismos scripts, mismos nombres de carpetas, mismos comandos de comprobación, mismas expectativas de PR.
Si no haces otra cosa, alinea:
/src, /test, /docs solo para excepciones)Hazla lo bastante pequeña para que los equipos no la salten:
install + dev)test, lint y formatEl mayor riesgo es copiar un template antiguo “porque funcionó el año pasado.” Dependencias obsoletas, scripts legacy o patrones abandonados se propagan rápido cuando están en un starter.
Trata los templates como productos: versiona, revísalos con regularidad y actualízalos cuando cambien tus convenciones. (Si tu plataforma soporta snapshots y rollback—Koder.ai lo hace—úsalo para iterar de forma segura en los starters sin romper la línea base de todos.)
Reducir la documentación no significa dejar a la gente adivinar. Significa hacer el “camino feliz” tan consistente que la mayoría de las preguntas se respondan por sí mismas, y solo las partes realmente inusuales necesiten redactarse.
Busca los lugares donde la gente repite las mismas preguntas en Slack, comentarios de PR, reuniones o sesiones de onboarding. Unos prompts útiles:
Si escuchas la misma pregunta dos veces, probablemente no necesitas más prosa—necesitas una convención.
Para cada pregunta repetida, decide cuál de estas es cierta:
Una regla útil: si una desviación no ahorra tiempo real ni evita riesgo real, probablemente no vale la confusión continua.
Mantén una única página corta (p. ej., /docs/conventions) que liste:
Limítate a lo que alguien necesita en su primera semana. Si la página comienza a crecer, suele ser señal de que debes simplificar la base de código en lugar de documentarla más.
Las apps evolucionan. Programa una revisión ligera cada trimestre:
Prefiere los valores por defecto del framework siempre que sea posible, y documenta solo lo que difiere—de forma clara, breve y en un solo lugar.
Las convenciones de un framework son los patrones por defecto que el framework espera que sigas: estructura de carpetas, nombrado, enrutamiento, acceso a datos y comandos comunes. Si te ciñes a ellas, otros desarrolladores pueden inferir dónde están las cosas y cómo funcionan sin leer documentación específica del proyecto.
Porque es difícil mantener la prosa precisa a medida que cambia la base de código. La documentación existe principalmente para:
Las convenciones cubren las dos primeras al hacer la estructura predecible.
No. Las convenciones reducen la documentación sobre lo obvio (dónde van los archivos, cómo se conectan las rutas), pero aún necesitas documentar lo que es específico del proyecto: reglas de negocio, desviaciones intencionadas y decisiones clave. Piensa en “menos documentación, documentación de mayor valor”.
Estandarizan las preguntas recurrentes del “día uno”:
Cuando el código sigue un patrón conocido, el árbol de directorios y los nombres actúan como señales. Un recién llegado puede navegar por expectativa (por ejemplo, “las plantillas están en templates/”, “las migraciones están en migrations/”) en vez de leer una larga página de arquitectura que pueda estar desactualizada.
Codifican las convenciones en valores por defecto para que la gente no dependa de la memoria. Los buenos scaffolds generan:
Esto evita la deriva y mantiene el “mapa” consistente entre características.
Lo notarás cuando los desarrolladores no puedan predecir dónde van las cosas o cómo se llaman. Señales comunes:
UserService vs UsersManager vs user_service)Entonces el equipo compensa con explicaciones en Slack, PRs más largos y “docs rápidas” que se quedan obsoletas.
Personaliza solo cuando haya un beneficio claro y deja una nota ligera que explique la desviación:
README.md dentro de la carpeta inusual/docs/decisions o similarCaptura qué cambió, por qué y cuál debe ser el enfoque estándar en el futuro.
Comienza por una base pequeña y práctica:
Manténlo ligero y exige que se actualice durante la revisión de código cuando un cambio introduzca una nueva excepción.
Usa la automatización para hacer las convenciones ejecutables:
Cuando las comprobaciones fallan en desarrollo local o en PRs, los desarrolladores aprenden las reglas de inmediato, y los revisores dedican menos tiempo a vigilar el estilo.
Cuando eso es predecible, el repositorio se vuelve autoexplicativo.