Skip to content

Reglas de Arquitectura y Buenas Prácticas

1. Reglas generales

  • La app se desarrolla en Kotlin + XML
  • La UI debe vivir en presentation
  • La lógica de negocio debe vivir en domain
  • El acceso a datos debe vivir en data
  • Las utilidades compartidas deben vivir en core
  • La navegación debe estar centralizada
  • No debe haber lógica compleja dentro de Activity o Fragment
  • No acceder directamente a data desde presentation
  • Toda comunicación debe pasar por domain
  • Evitar clases con más de una responsabilidad
  • Usar nombres en Inglés (Dejar comentarios si son nombres propios del negocio)

2. Reglas para Presentation

Fragments

  • Cada pantalla debe implementarse preferentemente como Fragment
  • El Fragment solo debe encargarse de:
  • renderizar UI
  • escuchar eventos de usuario
  • observar estado del ViewModel
  • delegar acciones al ViewModel

ViewModels

  • Deben contener lógica de presentación, no lógica visual
  • No deben conocer clases Android innecesarias como Activity o View
  • Deben exponer estado inmutable hacia la UI
  • Deben usar StateFlow, SharedFlow o LiveData según la estrategia del proyecto
  • Deben delegar la lógica de negocio a UseCases

Activities

  • Deben usarse como contenedor de navegación y configuración global
  • Evitar meter lógica de pantallas dentro de MainActivity

3. Reglas para Domain

  • Debe ser independiente de Android
  • Debe contener:
  • modelos de dominio
  • contratos de repositorio

  • casos de uso

  • No debe conocer Retrofit, Room, XML ni Context

  • Cada UseCase debe representar una única responsabilidad
  • Evitar UseCases con múltiples responsabilidades

4. Reglas para Data

  • Implementa repositorios del dominio
  • Se encarga de:
  • llamadas de red
  • persistencia local
  • mapeo de datos
  • manejo de errores técnicos
  • No debe contener lógica de UI
  • No debe devolver DTOs a la UI
  • Siempre mapear a modelos del dominio

5. Reglas para Core

Debe contener: - validaciones - extensiones - logger - constantes - wrappers comunes - manejo de errores - utilidades - clases base

Ejemplo:

core/
├── extensions/
├── utils/
├── validation/
├── logger/
├── session/
└── common/

6. Convenciones de nombres

Clases

  • PascalCase
  • Ejemplo: LoginFragment, HomeViewModel, GetUserProfileUseCase

Funciones y variables

  • camelCase
  • Ejemplo: loadUserData(), isLoading

Constantes

  • UPPER_SNAKE_CASE
  • Ejemplo: MAX_RETRY_COUNT

Layouts XML

  • snake_case
  • Ejemplo: fragment_login.xml, item_contract.xml

Paquetes

  • lowercase
  • Evitar guiones bajos innecesarios
  • Preferir nombres claros y consistentes

7. Reglas de navegación

  • Centralizar navegación en NavHostFragment y navigation.xml
  • No hardcodear rutas o acciones por todo el proyecto
  • La navegación debe dispararse desde la UI
  • Si se necesita comunicar navegación desde ViewModel, usar eventos de UI

8. Reglas de UI XML

  • No hardcodear textos
  • Todos los textos deben ir en strings.xml
  • No hardcodear colores repetidos
  • Reutilizar estilos y temas
  • Separar layouts complejos en includes o componentes reutilizables
  • Mantener nombres XML claros y consistentes

9. Reglas de reutilización

Todo lo que se repita varias veces debe extraerse a: - core si es lógica/utilidad - presentation/components si es UI reutilizable - domain/usecase si es comportamiento de negocio compartido

10. Reglas de calidad

  • Funciones cortas y legibles
  • Evitar clases gigantes no más de 350 líneas en una clase
  • Evitar métodos con múltiples responsabilidades
  • Evitar booleanos ambiguos
  • Preferir sealed class o enum class cuando aplique
  • No duplicar lógica
  • No usar if else gigantes
  • No usar nombres genéricos

11. Reglas de testing

  • tests unitarios para UseCases
  • tests para validaciones
  • tests para ViewModels
  • tests de repositorio cuando la lógica lo amerite

12. Convención de ramas

13. Reglas del flujo de desarrollo

  • Crear una rama a partir de la rama principal del feature, incluyendo el identificador CUSP
  • Todos los cambios deben integrarse a la rama principal del feature mediante Pull Requests (PR)
  • Evitar commits grandes; realizar commits pequeños y descriptivos por cada avance del feature
  • Todos los PR deben contar con al menos un revisor aprobado antes de realizar el merge
  • Incluir una breve descripción de los cambios realizados en cada PR
  • Agregar evidencia cuando aplique capturas de pantalla o video (Opcional)
  • Cualquier cambio relacionado con configuración global del proyecto debe ser consultado y validado con todo el equipo Android

14. Convención de commits (opcional)

  • Se recomienda utilizar mensajes de commit claros y estandarizados
  • feat: agregar login con validación
  • fix: corregir crash en pantalla de inicio
  • refactor: mejorar estructura del ViewModel
  • chore: actualizar dependencias

Conclusión

La meta no es tener más módulos, sino construir una aplicación clara, ordenada y mantenible App-Motor debe mantenerse como un proyecto único, pero con una arquitectura sólida que permita escalar sin perder control ni calidad en el código.