Skip to content

Autoren-Regeln

Normative Vorgaben für Autoren von .puml-Diagrammen in Projekten mit doubleSlash Gen2 Theme.

Notation & Benennung

Element-Namen

Element Konvention Beispiel
Klassen, Services PascalCase OrderService, PaymentGateway
Use Cases Sentence case in Klammern (Place order)
Aktoren Klartext, ggf. Anführungszeichen Actor "Customer"
Packages / Systeme Klartext rectangle "Online Shop"

Titel-Format

Soll: [Projekt] — [Diagrammtyp]: [Subject]

title [Shop] — Sequence: Checkout Flow
title [ERP] — Datenmodell: Auftragsverwaltung

Sprache

Kontext Empfehlung
Architektur-Diagramme in DE-Projekten Deutsch (Labels, Titel, Notes)
Code-Artefakte Englisch (Klassennamen, Dateinamen)
PUML-Kommentare Englisch (Repo-Konvention)

Struktur einer .puml-Datei

@startuml eindeutiger-name
!include .../doubleslash/doubleslash-gen2.puml   ' oder light/dark/system/gantt
title [Projekt] — [Typ]: [Subject]
' Diagramminhalt
@enduml

Do / Don't-Galerie

1. Theme-Include statt Inline-skinparam

@startuml
!include https://raw.githubusercontent.com/doubleSlashde/umltheme/main/doubleslash/doubleslash-gen2.puml
participant A
participant B
A -> B : styled by theme
@enduml

@startuml
!include https://raw.githubusercontent.com/doubleSlashde/umltheme/main/doubleslash/doubleslash-gen2.puml
skinparam classBackgroundColor #FF0000
class ImportantService
@enduml

2. Stereotyp statt manueller Farbe

@startuml
!include https://raw.githubusercontent.com/doubleSlashde/umltheme/main/doubleslash/doubleslash-gen2.puml
class BillingService <<external>>
@enduml

@startuml
!include https://raw.githubusercontent.com/doubleSlashde/umltheme/main/doubleslash/doubleslash-gen2.puml
skinparam classBackgroundColor #FF0000
class ImportantService
@enduml

3. Gen2 statt Legacy-Theme

!include .../doubleslash/doubleslash-gen2.puml

@startuml
!include https://raw.githubusercontent.com/doubleSlashde/umltheme/main/puml-theme-doubleslash-sequence.puml
participant A
participant B
A -> B : legacy theme
@enduml

4. Konsistenter Modus

!include .../doubleslash/dark.puml

@startuml
!$PUML_MODE = "light"
!$PUML_BGCOLOR = "white"
!include https://raw.githubusercontent.com/doubleSlashde/umltheme/main/doubleslash/doubleslash-gen2.puml
note as AntiPattern
  **Do not** set !$PUML_MODE = "dark" after this include —
  tokens are already assigned for light mode.
end note
class BrokenExample
@enduml

5. CSS-Padding (PlantUML ≥ 1.2026.3)

@startuml
!include https://raw.githubusercontent.com/doubleSlashde/umltheme/main/doubleslash/doubleslash-gen2.puml
<style>
element {
  Padding 2
}
participant {
  Margin 5 40
  Padding 15 20
}
</style>
participant A
participant B
A -> B : hello
@enduml

skinparam ParticipantPadding 200
skinparam Padding 99

6. Externe Systeme kennzeichnen

@startuml
!include https://raw.githubusercontent.com/doubleSlashde/umltheme/main/doubleslash/doubleslash-gen2.puml
participant "Internal API" as API
participant "Payment Provider" as Pay <<external>>
API -> Pay : authorize payment
@enduml

participant "Legacy" #CCCCCC

7. System-Bundle für C4

@startuml
!include https://raw.githubusercontent.com/doubleSlashde/umltheme/main/doubleslash/puml-theme-gen2-system.puml
rectangle "System" <<context>> {
  rectangle "Web App" <<container>>
}
@enduml

!include .../doubleslash-gen2.puml
skinparam RectangleBorderColor red

8. Gantt-Doppel-Include

@startgantt
!include https://raw.githubusercontent.com/doubleSlashde/umltheme/main/doubleslash/doubleslash-gen2.puml
!include https://raw.githubusercontent.com/doubleSlashde/umltheme/main/doubleslash/puml-theme-gen2-gantt.puml
[Task A] lasts 5 days
[Task B] lasts 3 days
@endgantt

@startgantt
!include .../pgantt-theme-doubleslash.puml
@endgantt

9. Keine überladenen Diagramme

Fokussiertes Sequenzdiagramm mit 4–6 Participant, gruppiert mit ==

20+ Participant ohne Gruppierung, Inline-Farben pro Nachricht

10. Semantik über Theme-Prozeduren

note right: $success(Completed) $failure(Failed)

note right: <color:#00FF00>Completed</color>

11. Keine Schattierung aktivieren

Theme-Default (shadowing false)

skinparam shadowing true

12. Titel über Theme, nicht inline formatieren

title [Project] — Class: Domain Model

title <size:40><color:red>Huge Red Title</color></size>

Autor-Lokal: Wann erlaubt?

Erlaubt (mit Begründung) Verboten
left to right direction Hardcoded Hex-Farben
hide stereotype, hide circle Globale skinparam-Overrides
top to bottom direction Legacy-Theme-URLs
Diagramm-spezifisches Layout Mix light + dark Includes
!pragma für Einzelfall-Layout Duplizieren von Theme-Molekülen

Siehe auch