Manifest de les bones pràctiques

1. Introducció

1.1 Propòsit del manifest

Aquest manifest recull les bones pràctiques que tot l'equip hauria de seguir per garantir la qualitat, mantenibilitat i escalabilitat dels nostres projectes. És una guia per assegurar que el codi que escrivim no només funcioni, sinó que també sigui fàcil de comprendre, provar i evolucionar amb el temps.

1.2 Per què necessitem bones pràctiques?

• Estandardització: Facilitar la col·laboració entre desenvolupadors.
• Mantenibilitat: Reduir costos a llarg termini i evitar acumulació de deute tècnic.
• Qualitat: Assegurar que el producte final sigui robust i fiable.
• Escalabilitat: Preparar el codi perquè pugui créixer amb noves funcionalitats.

2. Principis fonamentals

2.1 Què és la Clean Architecture?

La Clean Architecture és un estil d'arquitectura que organitza el codi en capes amb responsabilitats clares, assegurant que el nucli de l'aplicació (Domini) sigui independent de detalls com frameworks, bases de dades o interfícies d'usuari. Això ens permet mantenir el codi clar, modular i fàcil d'escalar.

2.1.1 Filosofia i objectius

• Independència: El Domini no depèn de cap detall tècnic ni d'implementació.
• Modularitat: Les capes estan separades i tenen responsabilitats específiques.
• Testabilitat: El codi és fàcil de provar gràcies a l’aïllament de les seves dependències.
• Mantenibilitat: Afegir o modificar funcionalitats és senzill i no trenca el codi existent.

2.1.2 Importància de SOLID

Els principis SOLID són essencials per implementar i mantenir la Clean Architecture:

1. Single Responsibility Principle (SRP): Cada classe o mòdul ha de tenir una única responsabilitat.
2. Open/Closed Principle (OCP): El codi ha d'estar obert a extensió però tancat a modificació.
3. Liskov Substitution Principle (LSP): Les subclasses han de poder substituir les seves classes base sense errors.
4. Interface Segregation Principle (ISP): Les interfícies han de ser petites i específiques.
5. Dependency Inversion Principle (DIP): Les capes superiors depenen d'abstraccions, no d'implementacions concretes.

2.2 Principis de Clean Code

El Clean Code complementa la Clean Architecture per garantir que el codi sigui llegible i mantenible. Alguns principis clau:

• Simplicitat: Evita la complexitat innecessària, fes que el codi sigui fàcil d'entendre.
• Només una responsabilitat: Les classes, mètodes i funcions han de tenir un únic propòsit.
• Evita duplicacions: Mantingues la DRY (Don't Repeat Yourself) per facilitar el manteniment.
• Nomenclatura clara: Utilitza noms descriptius per a variables, funcions i classes.
• Testabilitat: Escriu codi pensant en la seva prova, fent-lo modular i desacoblat.

3. Bones pràctiques de desenvolupament

3.1 Estructura de carpetes i organització del codi

• Organitza el codi per capes seguint la Clean Architecture: Presentació, Aplicació, Domini ,Infraestructura i Servei.
• No barregis responsabilitats dins de les carpetes (p. ex., no col·loquis serveis dins de la capa de Domini).

3.2 Nomenclatura clara i consistent

Utilitza noms descriptius per a classes, mètodes i variables.
Exemple:

• BookService és millor que Service1.
• GetBooksByAuthor() és millor que MethodX().
• Usa verbs per a mètodes i substantius per a classes.
• Segueix un estil de nomenclatura uniforme, com PascalCase per a classes i camelCase per a variables.

3.3 Testing i assegurament de qualitat

• Els tests han de ser clars i provar només una responsabilitat.
• Utilitza eines com xUnit i FluentAssertions per escriure tests robustos i llegibles.
• Aplica proves de regressió quan es facin canvis significatius al codi.
• Usa eines d’anàlisi (p. ex., SonarQuebe) per detectar problemes potencials automàticament.

4. Capa de Domini

• Els models del Domin (entitats) han de representar l’essència del negoci i han de ser independents de qualsevol tecnologia o implementació.
• Evita incloure dependències externes als models.
• Les entitats han de ser POCO

5. Capa d’Aplicació

5.1 Ús de serveis i patrons

• La capa d’Aplicació és responsable de coordinar les accions entre el Domini i altres capes, mantenint la lògica empresarial en el Domini.
• Utilitza patrons com Mediator o Command/Query per gestionar sol·licituds i separar responsabilitats.

5.2 Evitar fugues de lògica cap a altres capes

• Mantingues aquesta capa desacoblada de detalls d’implementació com frameworks o bases de dades.
• No facis trucades directes a bases de dades o APIs externes des dels serveis d’aplicació.

6. Capa de Serveis

6.1 API: Controladors simples sense lògica i bones pràctiques

• Els controladors han de ser el punt d’entrada per a la comunicació amb l'API, però no han de contenir lògica de negoci ni cap tipus de càlcul.
• Limita els controladors a:
  • Rebre sol·licituds (requests).
    • Delegar la lògica als serveis o handlers d’Aplicació.
    • Retornar respostes (responses).

6.2 Background Services: Optimització i gestió d’excepcions

• Utilitza Background Services per a tasques que no requereixin resposta immediata, com processament en segon pla o notificacions.
• Divideix les tasques llargues en passos més petits per evitar bloquejos del sistema.
• Captura i gestiona excepcions en els serveis de segon pla.
• Afegeix logs i mètriques per monitoritzar el rendiment i detectar problemes a temps.

7. Capa d’Infraestructura

7.1 Accés a dades: Repositoris genèrics i específics

• La capa d’Infraestructura és responsable d’implementar l’accés a bases de dades, serveis externs i altres fonts de dades.
• Utilitza repositoris genèrics per a operacions comunes i crea repositoris específics per a funcionalitats especials.
• Mantingues el codi de la capa d’Infraestructura desacoblat de la lògica del Domini. Els repositoris només han de contenir operacions tècniques.

7.1.1 Bones pràctiques per a l’accés a dades:

1. Eficiència en les consultes:

   • Optimitza consultes amb Include només quan sigui necessari.

2. Gestió d’excepcions:

   • Gestiona les excepcions relacionades amb la base de dades de manera centralitzada.
   • Registra els errors però evita exposar informació tècnica sensible.

3. Migracions:

   • Automatitza les migracions per assegurar que la base de dades estigui sincronitzada amb el model.

4. Connexions:

   • Configura timeouts raonables per evitar bloquejos.

7.2 Accés a APIs externes

• Utilitza NSwagStudio per generar els clients d'aquestes APIs externes.
• Afegeix el comentari // <auto-generated /> al principi de cada client auto-generat.
• Testeja be aquests clients auto-generats.

8. Capa de Presentació

8.1 MAUI: Bones pràctiques en el desenvolupament d’interfícies i optimització per a dispositius

• La capa de Presentació és responsable de la interacció directa amb l'usuari.

8.1.1 Bones pràctiques per a desenvolupament amb MAUI:

1. Separació de responsabilitats:

   • Utilitza el patró MVVM (Model-View-ViewModel) per separar la lògica de presentació de la interfície d'usuari.
   • Mantingues els ViewModels lleugers i centrats en la lògica específica de la interfície.

2. Interfícies d’usuari escalables i responsives:

   • Aplica estils compartits i recursos per mantenir consistència en totes les pantalles.

3. Optimització de rendiment:

   • Minimitza el treball a la UI Thread; delega operacions costoses als serveis de segon pla.

4. Gestió de navegació:

   • Utilitza el sistema de Shell per gestionar la navegació de manera estructurada i eficient.
   • Mantingues les rutes organitzades i reutilitza pàgines quan sigui possible.

9. Principis de col·laboració i estil de codi

9.1 Revisió de codi (Pull Request)

• Objectiu de la revisió:

  • Assegurar que el codi compleixi amb les bones pràctiques, sigui funcional i de qualitat.
  • Ajudar a millorar el codi a través de feedback constructiu.

• Bones pràctiques per a Pull Requests:

  • Mantingues els canvis petits i enfocats a una tasca específica.
  • Proporciona descripcions clares i contextuals a les Pull Requests.
  • Fer commits descriptius.
  • Passar tots els tests abans
  • Executar l'aplicació per assegurar que almenys s'aixeca.

9.2 Format i convencions

• Adopta una guia d’estil compartida pel projecte (com la guia d’estil de .NET).

• Bones pràctiques en convencions:

  • Utilitza noms descriptius i coherents per a variables, mètodes i classes.
  • Escriu comentaris només quan siguin necessaris; el codi ben escrit hauria de ser autoexplicatiu.

10. Reflexió i millora contínua

10.1 Com adaptar-nos als canvis

• Acceptar l’evolució tecnològica:

  • Les eines, llenguatges i metodologies evolucionen constantment. Hem d’estar disposats a adaptar-nos i aprendre noves tecnologies si aporten valor al projecte.
  • Mantingues l’equip informat amb formacions, conferències i articles tècnics rellevants.

• Flexibilitat en el disseny:

  • Planifica l’arquitectura per suportar canvis futurs amb un mínim impacte.
  • Implementa patrons que permetin escalar i adaptar-se (com el patró estratègia o dependency injection).

10.2 Revisar i ajustar el manifest de manera periòdica

• Importància de la revisió:

  • Aquest manifest ha de ser una eina viva que reflecteixi la realitat i les necessitats de l’equip.
  • Programa sessions periòdiques per revisar i actualitzar els punts que s’hagin quedat obsolets o que ja no s’apliquen.

• Feedback de l’equip:

  • Involucra tots els membres en el procés de revisió. Cada punt hauria de ser consensuat i útil per al dia a dia.
  • Utilitza eines com retrospectives per recollir idees i millores que es puguin afegir al manifest.

10.3 Millora contínua com a filosofia

• No conformar-se:

  • Busca maneres d’optimitzar i millorar la qualitat del codi i els processos.
  • Analitza errors i incidents per aprendre d’ells i evitar-los en el futur.

• Documentació i coneixement compartit:

  • Mantingues documentat el coneixement clau i les millors pràctiques per facilitar el creixement de l’equip.
  • Fomenta una cultura d’ajuda mútua i mentoratge dins de l’equip.

Aquest punt final ens recorda que l’objectiu principal és mantenir l’eficiència, qualitat i adaptabilitat en el temps.

Hem de ser responsables en l’aplicació de les bones pràctiques sense caure en dogmes ni rigideses excessives.

Cada projecte i equip té necessitats específiques, i el nostre enfocament ha de ser sempre pràctic i adaptatiu. Apostem per una mentalitat de millora contínua, tant a nivell tècnic com personal.

El veritable creixement es troba en l’equilibri: ser capaços d’escriure codi de qualitat mentre aprenem a ser professionals més complets, col·laboratius i innovadors.

Continuem aprenent, creixent i millorant junts! 🚀