---
name: clean-code-analysis
description: >-
  Systematische Clean Code Analyse basierend auf den Prinzipien von Robert C. Martin.
  Use when asked to "check clean code", "analyze code quality", "SOLID principles check",
  "Clean Code prüfen", "Code-Qualität analysieren", "readability check", "code review",
  "naming conventions check", "function length analysis", or when reviewing pull requests
  for code quality. Evaluates naming, function design, comments, formatting, error handling,
  and SOLID adherence. Produces actionable improvement suggestions.
---

# Clean Code Analysis Skill

Systematische Analyse von Code nach Clean Code Prinzipien. Basiert auf "Clean Code" von Robert C. Martin und etablierten Best Practices.

## Analyse-Workflow

### Phase 1: Schnell-Scan

Führe automatische Checks durch, bevor du manuell analysierst.

**Universell (alle Sprachen):**

```bash
# Clean Code Metriken sammeln
./scripts/clean-code-check.sh [Pfad] --quick

# Oder manuell:
# 1. Lange Dateien finden
find . -name "*.ts" -o -name "*.js" -o -name "*.py" | xargs wc -l | sort -rn | head -20

# 2. Lange Funktionen finden (>30 Zeilen)
grep -rn "function\|def \|fn \|func " --include="*.ts" --include="*.py" | head -30

# 3. Tiefe Verschachtelung erkennen
grep -rn "^\s\{16,\}" --include="*.ts" --include="*.py" | head -20
```

**TypeScript/JavaScript:**

```bash
# ESLint mit Clean Code Regeln
npx eslint . --ext .ts,.js --rule 'max-lines-per-function: ["warn", 30]'
npx eslint . --rule 'complexity: ["warn", 10]'
npx eslint . --rule 'max-depth: ["warn", 4]'
npx eslint . --rule 'max-params: ["warn", 4]'
```

**Python:**

```bash
# Pylint Clean Code Checks
pylint --disable=all --enable=C0301,C0302,R0902,R0903,R0911,R0912,R0913,R0914,R0915 src/

# Radon für Komplexität
radon cc src/ -a -nc
```

### Phase 2: Naming Analysis

Prüfe systematisch alle Namen im Code.

#### 2.1 Variablen-Namen

| Regel | Gut | Schlecht |
|---|---|---|
| **Intention offenbaren** | `elapsedTimeInDays` | `d`, `time`, `x` |
| **Aussprechbar** | `generationTimestamp` | `genymdhms` |
| **Suchbar** | `MAX_STUDENTS_PER_CLASS` | `7` |
| **Kein Prefix-Müll** | `phoneNumber` | `m_phoneNumber`, `strPhoneNumber` |
| **Kontext geben** | `addressCity` | `city` (ohne Kontext) |

**Checkliste:**
- [ ] Keine Single-Letter-Namen (außer Loop-Counter `i`, `j`)
- [ ] Keine kryptischen Abkürzungen (`usr`, `mgr`, `btn`)
- [ ] Keine bedeutungslosen Namen (`data`, `info`, `temp`, `result`)
- [ ] Keine Noise-Words (`theUser`, `aProduct`, `actualValue`)
- [ ] Boolean-Namen als Frage: `isActive`, `hasPermission`, `canEdit`

#### 2.2 Funktions-Namen

| Regel | Gut | Schlecht |
|---|---|---|
| **Verb + Nomen** | `calculateTotalPrice()` | `total()` |
| **Beschreibt was, nicht wie** | `sendEmail()` | `socketWriteEmailData()` |
| **Keine Side-Effects andeuten** | `checkPasswordAndInitSession()` | `checkPassword()` (init versteckt) |
| **Konsistenz** | `get/set/fetch/retrieve` einheitlich | gemischt |

**Anti-Patterns:**
- `doStuff()`, `handleData()`, `processItem()` — zu generisch
- `getUserAndSendEmailAndLogActivity()` — macht zu viel
- `temp()`, `foo()`, `test2()` — bedeutungslos

#### 2.3 Klassen/Modul-Namen

| Regel | Gut | Schlecht |
|---|---|---|
| **Substantive, keine Verben** | `UserAccount` | `ManageUsers` |
| **Spezifisch** | `InvoiceCalculator` | `Manager`, `Processor`, `Handler` |
| **Keine Info-Noise** | `User` | `UserInfo`, `UserData`, `UserObject` |

### Phase 3: Function Analysis

Analysiere jede Funktion nach Clean Code Kriterien.

#### 3.1 Größe

| Metrik | Optimal | Akzeptabel | Problematisch |
|---|---|---|---|
| **Zeilen** | < 10 | < 20 | > 30 |
| **Parameter** | 0-2 | 3 | > 4 |
| **Verschachtelung** | 1-2 | 3 | > 4 |
| **Cyclomatic Complexity** | < 5 | < 10 | > 15 |

#### 3.2 Single Responsibility

Jede Funktion sollte **eine Sache** tun. Warnsignale:

- [ ] Name enthält "And" oder "Or"
- [ ] Funktion hat mehrere Abstraktionsebenen
- [ ] Mehrere Gründe für Änderung
- [ ] Schwer zu beschreiben ohne "und"

**Test:** Kann die Funktion in einem Satz ohne "und" beschrieben werden?

#### 3.3 Abstraktions-Ebenen

Alle Statements in einer Funktion sollten auf **derselben Abstraktionsebene** sein.

```typescript
// ❌ SCHLECHT: Gemischte Abstraktionsebenen
function renderPage() {
  const html = getPageHtml();            // Hoch
  html.replace(/&/g, '&amp;');           // Niedrig (Detail)
  return appendFooter(html);             // Hoch
}

// ✅ GUT: Einheitliche Abstraktionsebene
function renderPage() {
  const html = getPageHtml();
  const sanitizedHtml = escapeHtmlEntities(html);
  return appendFooter(sanitizedHtml);
}
```

#### 3.4 Command-Query Separation

Funktionen sollten entweder:
- **Etwas tun** (Command) — void/Unit zurückgeben
- **Etwas beantworten** (Query) — Wert zurückgeben, keine Side-Effects

```typescript
// ❌ SCHLECHT: Mischt Command und Query
function setAndReturnUser(id: string): User {
  this.currentUser = fetchUser(id);
  return this.currentUser;
}

// ✅ GUT: Getrennt
function setCurrentUser(id: string): void { ... }
function getCurrentUser(): User { ... }
```

### Phase 4: Comment Analysis

Kommentare sind oft ein Zeichen für schlechten Code. Analysiere kritisch.

#### 4.1 Gute Kommentare (selten nötig)

| Typ | Beispiel |
|---|---|
| **Legal** | Copyright-Header |
| **Informativ** | Regex-Erklärung: `// Format: YYYY-MM-DD` |
| **Intent** | `// Prefer empty result over throwing exception for API compatibility` |
| **Warning** | `// WARNING: Not thread-safe, use only in single-threaded context` |
| **TODO** | `// TODO(#123): Implement caching when load increases` |
| **API-Doc** | JSDoc/Docstring für öffentliche APIs |

#### 4.2 Schlechte Kommentare (sofort entfernen)

| Typ | Beispiel | Besser |
|---|---|---|
| **Redundant** | `// Increment counter` `counter++` | Löschen |
| **Auskommentierter Code** | `// oldFunction()` | Git-History nutzen |
| **Journal** | `// Added 2024-01-15 by John` | Git-Blame nutzen |
| **Noise** | `// Default constructor` | Löschen |
| **Misleading** | Veralteter Kommentar | Aktualisieren oder löschen |
| **Mandated** | Javadoc für private Methoden | Löschen |

**Regel:** Wenn du einen Kommentar schreiben willst, frage zuerst: Kann ich den Code so umschreiben, dass der Kommentar unnötig wird?

### Phase 5: SOLID Analysis

Prüfe die SOLID-Prinzipien.

#### S — Single Responsibility Principle

- [ ] Jede Klasse hat nur **einen Grund** sich zu ändern
- [ ] Klasse kann in einem Satz ohne "und" beschrieben werden
- [ ] Keine "God Classes" mit > 500 LoC

**Smell:** Klasse importiert viele verschiedene Domains (DB, HTTP, UI, Business Logic)

#### O — Open/Closed Principle

- [ ] Erweiterung durch neue Klassen, nicht durch Änderung bestehender
- [ ] Keine `switch/case` oder `if/else` auf Typen
- [ ] Abstractions/Interfaces für variable Komponenten

**Smell:** Jedes neue Feature erfordert Änderung in derselben Datei

#### L — Liskov Substitution Principle

- [ ] Subtypen sind 100% kompatibel mit Basistypen
- [ ] Keine Override-Methoden die weniger tun als Basisklasse
- [ ] Keine Exceptions die Basisklasse nicht wirft

**Smell:** `instanceof` Checks nach Downcast

#### I — Interface Segregation Principle

- [ ] Kleine, spezifische Interfaces statt großer "fat" Interfaces
- [ ] Clients sind nicht von Methoden abhängig die sie nicht nutzen
- [ ] Interfaces nach Rolle, nicht nach Implementierung

**Smell:** Interface mit > 5 Methoden, von denen Clients nur 1-2 nutzen

#### D — Dependency Inversion Principle

- [ ] High-Level Module hängen von Abstractions ab
- [ ] Keine direkten Imports von Implementierungen in Business Logic
- [ ] Dependency Injection verwendet

**Smell:** `new ConcreteClass()` in Business Logic statt Injection

### Phase 6: Error Handling

#### 6.1 Exceptions vs. Error Codes

```typescript
// ❌ SCHLECHT: Error Codes
function getUser(id: string): User | null | -1 | -2 { ... }

// ✅ GUT: Exceptions oder Result Types
function getUser(id: string): User { throw new UserNotFoundError() }
// oder
function getUser(id: string): Result<User, UserError> { ... }
```

#### 6.2 Error Handling Checkliste

- [ ] Keine leeren Catch-Blöcke
- [ ] Exceptions werden nicht für Control Flow missbraucht
- [ ] Fehler-Kontext wird mitgegeben (was wurde versucht?)
- [ ] Keine generischen `catch(Exception e)`
- [ ] `null` wird nicht als Error-Indikator zurückgegeben
- [ ] Defensive Programming an System-Grenzen (externe APIs, User-Input)

### Phase 7: Formatting & Consistency

#### 7.1 Vertikale Formatierung

- [ ] Zusammengehöriger Code steht beisammen
- [ ] Konzeptuelle Trennung durch Leerzeilen
- [ ] Abhängige Funktionen nahe beieinander
- [ ] Caller über Callee

#### 7.2 Horizontale Formatierung

- [ ] Konsistente Einrückung (2/4 Spaces oder Tabs)
- [ ] Zeilen < 120 Zeichen
- [ ] Kein horizontales Alignment (verursacht Merge-Konflikte)

### Phase 8: Report erstellen

Erstelle den Report mit dem Template `./templates/clean-code-report.md`.

```markdown
# Clean Code Analysis Report — [Projekt/Modul]

## Score Summary
| Kategorie | Score | Bemerkung |
|---|---|---|
| Naming | [1-5] ⭐ | [Kurzbewertung] |
| Functions | [1-5] ⭐ | [Kurzbewertung] |
| Comments | [1-5] ⭐ | [Kurzbewertung] |
| SOLID | [1-5] ⭐ | [Kurzbewertung] |
| Error Handling | [1-5] ⭐ | [Kurzbewertung] |
| Formatting | [1-5] ⭐ | [Kurzbewertung] |
| **Gesamt** | [Durchschnitt] ⭐ | |

## Top 5 Verbesserungen
1. [Finding] — Datei:Zeile — Aufwand: [X]h
...

## Detaillierte Findings
[Nach Kategorie gruppiert]

## Positives
[Was bereits gut umgesetzt ist]
```

## Wichtige Regeln

1. **Konkrete Beispiele** — Jeder Finding muss eine konkrete Code-Stelle referenzieren
2. **Verbesserungsvorschlag** — Zu jedem Problem einen konkreten Lösungsvorschlag
3. **Pragmatisch** — Nicht jede Regel gilt in jedem Kontext (Prototypen, Scripts, etc.)
4. **Prioritäten setzen** — Die wichtigsten 5 Verbesserungen hervorheben
5. **Positives erwähnen** — Gute Patterns anerkennen, nicht nur kritisieren
6. **Kontext beachten** — Legacy Code, Zeitdruck, Team-Konventionen berücksichtigen

## Referenzen

- `./references/clean-code-principles.md` — Vollständige Prinzipien-Übersicht
- Robert C. Martin: "Clean Code" (2008)
- Martin Fowler: "Refactoring" (2018)