Shop Projekt - Dokumentation

Allgemeine Benennungsregeln

• Kurz, aber klar: So kurz wie möglich, so klar wie nötig für sofortiges Verständnis.
• Ein Konzept, ein Name: Einmal etablierte Fachbegriffe (z. B. Label, Order, User) werden projektweit durchgängig ohne Synonymwechsel verwendet.
• Standardisierte Bezeichner: Abkürzungen werden ausschließlich verwendet, wenn sie im Projekt-Glossar definiert und projektweit bekannt sind.
• Englisch im Code: Sämtliche Bezeichner, Variablen, Funktionen und Code-Kommentare werden konsequent auf Englisch verfasst.

Variablen- und Funktionsnamen

• Schreibweisen (Casing): camelCase für Variablen und Funktionen ($labelData, handleUpdate()), UPPER_SNAKE_CASE für Konstanten (cCg::DEFAULT_PSW).
• Verben für Aktionen & Funktionen: Funktionsnamen beginnen mit präzisen Standard-Verben (z. B. get, set, handle, check, export, load).
• Nomen für Daten & Objekte: Datenbehälter und Objekte werden als aussagekräftige Substantive benannt (routeConfig, navContext).
• Boolesche Zustände: Booleans werden als klare Zustandsaussagen mit Präfix formuliert (isOpen, hasAccess, canEdit).
• Varianten-Benennung: Abwandlungen derselben Grunddaten behalten den Basisnamen vorne und ergänzen das Suffix am Ende (z. B. $labelData → $labelDataFiltered → $labelDataExport).
• Lokale Schleifenzähler: Kurze Zähler wie $i oder $idx sind ausschließlich in engen, lokalen Schleifen zugelassen.

System-Präfixe & Klassen-Abkürzungen

Configuration- und Systemklassen, die hauptsächlich Konstanten gruppieren, werden bewusst sehr kurz gehalten, um die Lesbarkeit zu verbessern:

• c Präfix für Klassen (z. B. cCg für Core Configuration, cSession für die Session Klasse, cApp für die Anwendung).

Hinweis: Alle abgekürzten Systemklassen (cCg, cSc, cFc etc.) müssen im zentralen Projekt-Glossar sowie in den jeweiligen Klassen-Doc-Blocks vollständig dokumentiert sein.

Klassen, Dateien und Module

• Klassennamen als Domänenobjekte: Klassen repräsentieren klare Einheiten oder Services (z. B. AccessService, NavModel, LabelController).
• Rollenbasierte Dateinamen: Dateinamen kennzeichnen ihre architektonische Rolle über das Suffix (*.service.php, *.model.php, *.view.php, *.controller.php).
• Verantwortungsbezogene Module: Modul- und Ordnernamen spiegeln den fachlichen Zweck wider (z. B. navigation, label-management), nicht die technische Umsetzung.

Review-Checkliste

• Erfasst ein neuer Entwickler den Zweck des Namens ohne Zusatzwissen sofort?
• Ist der Name so kurz wie möglich, ohne präzise Bedeutung zu verlieren?
• Wird derselbe Fachbegriff in verwandten Dateien exakt gleich verwendet?
• Folgen Varianten dem Schema Basisname + Suffix (z. B. $labelDataFiltered)?