Conventions de nommage – Balyze
Traduction
Cette page est une traduction de la version anglaise, qui fait foi.
Objectif
Ces conventions de nommage ont pour but de garantir :
- une lecture immédiate du rôle d’un fichier sans l’ouvrir
- une base de code cohérente et maintenable
- une évolution sans dette technique de la v0 (ALPHA) à la BETA et au-delà
Le principe directeur est simple :
Lire un nom doit suffire à comprendre la responsabilité du code associé.
Conventions globales
Langue
- L’anglais est utilisé partout dans le code
- Le français est autorisé uniquement dans :
- la documentation
- le README
- les tickets et le Kanban
Structure des dossiers
- Respect strict de la structure Laravel
- Pas de dossiers génériques ou ambigus (Helpers, Utils, Common, etc.)
- Un dossier correspond à une responsabilité claire
Models (Eloquent)
Emplacement
app/Models
Règles de nommage
- Nom au singulier
- PascalCase
- Aucun suffixe ou préfixe
Exemples :
Application
Position
Document
User
Relations Eloquent
- Nom des méthodes explicite
- Singulier ou pluriel selon la relation
Exemples :
user()
applications()
documents()
Enums
Emplacement
app/Enums
Règles de nommage
- PascalCase
- Suffixe explicite selon le rôle
Exemples :
ApplicationStatus
DocumentType
Valeurs d’énumération
- Valeurs explicites
- Pas de valeurs magiques ailleurs dans le code
Policies
Emplacement
app/Policies
Règles de nommage
- Une policy par modèle
- Suffixe Policy
Exemples :
ApplicationPolicy
PositionPolicy
DocumentPolicy
Responsabilité
- Autorisation uniquement
- Aucune logique métier
- Les règles globales (super-admin) sont centralisées via Gate::before()
Services métier
Emplacement
app/Services
Règles de nommage
- Verbe + NomMétier + Service
- Une action métier par service
Exemples :
CreateApplicationService
UpdateApplicationStatusService
AttachDocumentToApplicationService
Règles
- Pas de classes génériques (Manager, Helper, Utils)
- La logique métier réside exclusivement dans les services
Controllers
Emplacement
app/Http/Controllers
Règles de nommage
- Suffixe Controller
- Un controller par ressource métier
Exemples :
ApplicationController
PositionController
DocumentController
Responsabilité
- Validation de la requête
- Appel des services métier
- Retour de la réponse HTTP
- Aucune logique métier
Form Requests
Emplacement
app/Http/Requests
Règles de nommage
- Verbe + Nom + Request
Exemples :
StoreApplicationRequest
UpdateApplicationRequest
AttachDocumentRequest
Tests
Emplacement
tests/Feature
tests/Unit
Règles de nommage
- Suffixe Test
- Aligné sur la classe ou le comportement testé
Exemples :
ApplicationPolicyTest
CreateApplicationServiceTest
Organisation
- Tests Feature : comportement global (auth, policies, routes)
- Tests Unit : logique métier isolée (services)
Migrations et base de données
Tables
- snake_case
- pluriel
Exemples :
applications
positions
documents
application_document
Colonnes
- snake_case
- suffixes explicites
Exemples :
user_id
created_at
deleted_at
document_type
Permissions (Spatie)
Format
resource.action
Exemples
applications.create
applications.view
applications.update
applications.delete
documents.create
documents.view
documents.update
documents.delete
Règles
- Permissions générales
- Les restrictions fines sont gérées par les Policies
- Le rôle admin est géré globalement via Gate::before()
Conclusion
Ces conventions constituent la base de développement du projet Balyze.
Elles s’appliquent dès la v0 (ALPHA) et sont conçues pour évoluer vers la BETA et les versions futures sans refactor structurel.