Dokumentationskonvention

---

Allgemeine Richtlinien

• Sprache: Alle Dokumentationen, Kommentare und API-Beschreibungen sind in englischer Sprache zu verfassen.
• Klarheit: Kommentare und Dokumentationen sollen präzise, verständlich und relevant sein. Überflüssige oder redundante Kommentare sind zu vermeiden.
• Formatierung: Einheitliche Formatierung gemäß den jeweiligen Framework- und Sprachstandards (z. B. Javadoc für Java, TSDoc für TypeScript).

---

Backend (Spring Boot)

• Javadoc:
  • Alle öffentlichen Klassen und Methoden müssen mit Javadoc-Kommentaren versehen werden. (exklusive Getter und Setter Methoden)
  • Beschreibung der Funktionalität, Parameter (@param) und Rückgabewerte (@return) ist verpflichtend.
  • Beispiel:

    /**
     * Retrieves a document by its ID.
     *
     * @param documentId the ID of the document
     * @return the document if found
     * @throws DocumentNotFoundException if the document does not exist
     */
    public Document getDocumentById(String documentId) {
        // Implementation
    }
    

• Komplexe Logik: Für komplexe Algorithmen oder Geschäftslogik sind zusätzliche Inline-Kommentare zu verwenden.
• API-Dokumentation: REST-Endpunkte sind mit OpenAPI zu dokumentieren.
• Konfigurationsdateien: Konfigurationsklassen und -dateien (z. B. application.yml) sind nur bei nicht standardmäßigen Parametern mit Kommentaren zu versehen, die die Bedeutung und den Zweck dieser Konfigurationsparameter erklären.

---

Frontend (Angular)

• TSDoc:
  • Alle öffentlichen Klassen und Methoden müssen mit TSDoc-Kommentaren dokumentiert werden.
  • Beispiel:

    /**
     * Fetches the document data from the server.
     * @param documentId The ID of the document to fetch.
     * @returns An observable containing the document data.
     */
    getDocument(documentId: string): Observable<Document> {
        return this.http.get<Document>(`/api/documents/${documentId}`);
    }
    

• Komponenten:
  • Jede Angular-Komponente muss eine kurze Beschreibung ihrer Funktionalität im Header-Kommentar enthalten.
  • Beispiel:

    /**
     * Component for displaying and editing a document.
     */
    @Component({
      selector: 'app-document-editor',
      templateUrl: './document-editor.component.html',
      styleUrls: ['./document-editor.component.css']
    })
    export class DocumentEditorComponent {
      // Implementation
    }
    

• Styles und Templates: Inline-Kommentare in HTML- und CSS-Dateien sind nur bei komplexen oder nicht offensichtlichen Strukturen zu verwenden.
• Services: Services müssen die bereitgestellten Funktionen und deren Verwendung dokumentieren.

---

Zusätzliche Konventionen

• Versionskontrolle: Änderungen am Code müssen durch entsprechende Aktualisierungen der Dokumentation begleitet werden, um Konsistenz sicherzustellen.
• Automatisierung: Tools wie Javadoc und Compodoc sind zu verwenden, um die Dokumentation automatisch zu generieren und aktuell zu halten.
• Review-Prozess: Dokumentationen sind Teil des Code-Review-Prozesses (siehe Merge Request Template) und müssen vor der Freigabe überprüft werden.