Style matters: Wie du Codeformatierung im Team richtig aufziehst

Uneinheitlich formatierter Code erschwert das Lesen und Verstehen von Code, verlangsamt Code Reviews und führt zu unnötigen Konflikten beim Zusammenführen von Änderungen. Teams, die effizient arbeiten wollen, brauchen klare Formatierungsregeln, die für alle Beteiligten nachvollziehbar sind. Besonders in Projekten mit mehreren Sprachen wie C#, TypeScript, HTML oder JSON ist Konsistenz entscheidend.

public class OrderService
{
    private ILogger _logger;

    public OrderService(ILogger logger)
    {
      _logger = logger;
    }

    private bool ValidateOrder(string name,
        List<Item> items,
        decimal totalAmount)
    {
      //simulate saving
    }

    public bool ProcessOrder(Order order)
    {
        if(order == null) _logger.LogError("Order is null.");

        if (!ValidateOrder(order.Name, order.Items, order.TotalAmount))
        {
            _logger.LogWarning("Order validation failed.");
            return false;
        }
        SaveOrder(order.Id, order.Name, order.Items, order.TotalAmount);
        _logger.LogInformation("Order processed successfully.");
        return true;
    }

    private bool ValidateOrder(string name, List<Item> items, decimal totalAmount)
    {
      return order.Items.Any()
      && order.TotalAmount > 0;
    }
}

Mit den richtigen Tools lässt sich Formatierung automatisieren und zuverlässig prüfen. In diesem Artikel geht es darum, wie Teams einen gemeinsamen Stil finden, welche Werkzeuge sich für welche Sprache eignen und wie sich Formatierung nahtlos in den Entwicklungsprozess integrieren lässt.

Einheitliche Regeln im Team etablieren

Ein gemeinsamer Code-Stil sorgt für Klarheit im Projekt und reduziert Reibung im Alltag. Damit das funktioniert, muss sich das Team auf konkrete Regeln einigen. Diese Regeln sollten dokumentiert und für alle leicht zugänglich sein, zum Beispiel als Documentation as Code in einem zentralen Ordner im Repository wie docs/development/guidelines/coding-styles/{csharp,typescript,css}.md.

Ein Beispiel findet man im .NET Runtime Repository:

## C# Coding Style

The general rule we follow is "use Visual Studio defaults".

1.  We use Allman style braces, where each brace begins on a new line. A single line statement block can go without braces but the block must be properly indented on its own line and must not be nested in other statement blocks that use braces (See rule 18 for more details). One exception is that a using statement is permitted to be nested within another using statement by starting on the following line at the same indentation level, even if the nested using contains a controlled block.
2.  We use four spaces of indentation (no tabs).
    ...

Man muss dabei nicht bei null anfangen. Viele Plattformen und Sprachen bieten offizielle Styleguides, die sich als Grundlage eignen. Für C# gibt es beispielsweise die Microsoft .NET Coding Conventions, für TypeScript den TypeScript Style Guide und für viele Technologien ist der Google Style Guide eine bewährte Referenz. Diese Standards bieten eine solide Struktur und helfen, Diskussionen im Team abzukürzen. Wenn man sich nicht sicher ist, kann man auf diese Quellen verlinken oder sie als Default übernehmen.

Es reicht jedoch nicht aus, Regeln nur zu dokumentieren oder auf externe Quellen zu verweisen. In der Praxis liest kaum jemand solche Dokumente vollständig. Deshalb ist es entscheidend, die Einhaltung der Regeln automatisiert zu prüfen und den Code automatisch zu formatieren. Nur durch diese Automatisierung wird der Stil konsequent angewendet, unabhängig davon, wer den Code schreibt oder überprüft.

Welche Sprachen brauchen Formatierung – und wie geht man damit um

In modernen Projekten kommen oft viele verschiedene Sprachen und Dateitypen zum Einsatz. Neben klassischen Programmiersprachen wie C# oder TypeScript gehören auch HTML, CSS, JSON, YAML, Bicep, Markdown und XML dazu. Jede dieser Sprachen bringt eigene Konventionen und Besonderheiten mit, die bei der Formatierung berücksichtigt werden sollten.

Einheitliche Formatierung ist nicht nur bei Quellcode wichtig. Auch Konfigurationsdateien, Templates und Dokumentation profitieren davon. Besonders bei YAML oder JSON kann eine falsche Einrückung oder ein fehlendes Komma zu schwer nachvollziehbaren Fehlern führen. Markdown-Dateien wirken deutlich klarer, wenn Überschriften, Listen und Codeblöcke konsistent strukturiert sind.

Formatierung und Linting sind zwei unterschiedliche Dinge. Linter prüfen auf inhaltliche oder strukturelle Probleme, während Formatter sich um das Layout kümmern. Beide Werkzeuge ergänzen sich sinnvoll, sollten aber getrennt konfiguriert und eingesetzt werden. Wer Formatierung automatisiert, reduziert Fehlerquellen und sorgt für einheitliche Ergebnisse, unabhängig davon, welcher Editor oder welches Betriebssystem verwendet wird.

Tools zur automatischen Formatierung

Für fast jede Sprache gibt es Werkzeuge, die Code automatisch formatieren können. Diese Tools helfen dabei, den definierten Stil konsequent umzusetzen, ohne dass Entwickler:innen manuell eingreifen müssen. Für C# eignet sich dotnet format, das direkt mit der EditorConfig arbeitet und sich gut in Build-Prozesse integrieren lässt. Aber auch CSharpier ist eine beliebte Alternative, die ohne viel Konfiguration auskommt.

[*.cs]
indent_style = space
indent_size = 4
max_line_length = 120
csharp_new_line_before_open_brace = all

Die EditorConfig-Datei legt fest, welche Regeln gelten, und kann für verschiedene Sprachen angepasst werden TypeScript und JavaScript lassen sich mit Prettier und ESLint formatieren. HTML, CSS und Markdown können ebenfalls mit Prettier behandelt werden. Für Bicep gibt es das Kommando bicep format, das die Struktur der Infrastrukturdefinitionen vereinheitlicht. Auch JSON, YAML und XML lassen sich automatisiert formatieren. Auch JSON, YAML und XML lassen sich automatisiert formatieren. Tools wie jsonlint, yamllint oder xmllint sind dafür geeignet. Viele dieser Werkzeuge lassen sich direkt in die Entwicklungsumgebung einbinden oder über die Kommandozeile ausführen. Zusätzlich können sie in CI/CD-Pipelines integriert werden, zum Beispiel über GitHub Actions oder Azure DevOps. So wird sichergestellt, dass der Code nicht nur lokal, sondern auch beim Zusammenführen von Änderungen einheitlich bleibt.Tools wie jsonint, yamllint oder xmllint sind dafür geeignet. Viele dieser Werkzeuge lassen sich direkt in die Entwicklungsumgebung einbinden oder über die Kommandozeile ausführen. Zusätzlich können sie in CI/CD-Pipelines integriert werden, zum Beispiel über GitHub Actions oder Azure DevOps. So wird sichergestellt, dass der Code nicht nur lokal, sondern auch beim Zusammenführen von Änderungen einheitlich bleibt.

// prettierrc
{
  "printWidth": 120,
  "tabWidth": 2,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all"
}

Die Wahl des Tools hängt von der Sprache und dem Projektkontext ab. Wichtig ist, dass die Formatierung automatisiert erfolgt und nicht von der Aufmerksamkeit einzelner Entwickler:innen abhängt. Nur so bleibt der Stil konsistent und unabhängig von persönlichen Vorlieben.

Code-Style-Prüfung automatisieren

Automatisierte Formatierung ist ein wichtiger Schritt, aber sie reicht allein nicht aus. Zusätzlich sollte geprüft werden, ob der Code dem definierten Stil entspricht. Diese Prüfung kann lokal beim Entwickeln erfolgen oder zentral in der CI/CD-Pipeline. So wird sichergestellt, dass keine unformatierten oder inkonsistenten Änderungen in das Repository gelangen. Unsere Empfehlung: Prüft die Einhaltung der Formatierungsregeln so früh wie möglich, idealerweise direkt beim Speichern, als Pre-Commit Hook oder spätestens im Pull Request. Je früher automatisierte Tools eingesetzt werden, desto weniger Aufwand entsteht bei der Korrektur und desto konsistenter bleibt der Code im gesamten Projekt.

Für C# bietet dotnet format die Möglichkeit, den Code nicht nur zu formatieren, sondern auch zu überprüfen. Mit dem Parameter --verify-no-changes lässt sich sicherstellen, dass der Code bereits formatiert ist. Für TypeScript und JavaScript kann ESLint mit der Option --max-warnings=0 verwendet werden, um sicherzustellen, dass keine Verstöße durchrutschen. In Kombination mit Prettier lässt sich auch die Formatierung selbst als Fehler behandeln, wenn sie nicht korrekt ist.

Diese Prüfungen lassen sich in Git Hooks einbauen, zum Beispiel mit Husky und Lint-Staged. Alternativ können sie in Build-Pipelines integriert werden, etwa in GitHub Actions oder Azure DevOps. So wird die Einhaltung der Regeln nicht dem Zufall überlassen, sondern ist fester Bestandteil des Entwicklungsprozesses.

// package.json
"lint-staged": {
  "*.ts": ["eslint --fix", "prettier --write"],
  "*.md": ["prettier --write"]
}

Beispiele für konkrete Formatierungsregeln

Formatierungsregeln sollten nicht zu allgemein bleiben. Je konkreter sie sind, desto besser lassen sie sich automatisieren und umsetzen. Eine häufig diskutierte Regel ist die maximale Zeilenlänge. Viele Teams setzen hier ein Limit von 120 oder 140 Zeichen. Das hilft, Code in Tools wie GitHub oder IDEs besser lesbar zu halten. Zu kurze Grenzen wie 80 Zeichen können jedoch zu unnötigen Umbrüchen führen und die Lesbarkeit verschlechtern. Auch für breite Monitore sind kürze Zeilen sinnvoll, da mehrere Dateien nebeneinander angezeigt werden können.

Auch die Reihenfolge von Elementen innerhalb einer Klasse ist ein typisches Thema. Manche Teams bevorzugen, zuerst statische Mitglieder zu definieren, dann Felder, gefolgt von Konstruktoren, Properties und Methoden. Andere sortieren nach Sichtbarkeit, also erst private, dann protected und zuletzt public. Wichtig ist, dass die gewählte Struktur konsequent angewendet wird und sich im Team etabliert.

Weitere Regeln betreffen Leerzeilen zwischen Methoden, Einrückung mit Tabs oder Spaces, Klammerstil und die Sortierung von Imports. Viele dieser Regeln lassen sich über Tools wie EditorConfig, ESLint oder Prettier definieren und automatisch prüfen. Je klarer die Regeln sind, desto weniger Diskussionen entstehen im Alltag.

// eslint.config.mjs
"@typescript-eslint/member-ordering": [
  "error",
  {
    "default": [
      "signature",
      "public-static-field",
      "protected-static-field",
      "private-static-field",
      "public-instance-field",
      "constructor",
      "public-instance-method",
      "private-instance-method"
    ]
  }
]

Best Practices für Teams

Einheitliche Formatierung funktioniert am besten, wenn sie nicht nur innerhalb eines Projekts, sondern auch teamübergreifend abgestimmt ist. Idealerweise gelten dieselben Regeln für alle Projekte, Repositories und Teams innerhalb einer Organisation. Das reduziert Reibung, erleichtert die Zusammenarbeit und sorgt dafür, dass Entwickler:innen nicht bei jedem neuen Projekt neue Regeln lernen müssen. Besonders beim Onboarding neuer Kolleginnen und Kollegen ist das ein großer Vorteil.

Eine zentrale Konfigurationsdatei wie .editorconfig hilft dabei, Regeln für verschiedene Sprachen und Editoren einheitlich festzulegen. Diese Datei sollte im Repository liegen, damit alle Teammitglieder automatisch dieselben Einstellungen verwenden. Auch Tools wie Prettier oder ESLint lassen sich mit gemeinsamen Konfigurationen über mehrere Projekte hinweg nutzen, zum Beispiel über gemeinsam gepflegte npm-Pakete oder NuGet-Pakete mit Style-Regeln.

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.cs]
indent_style = space
indent_size = 4

[*.ts]
indent_style = space
indent_size = 2

Formatierung sollte nicht manuell diskutiert werden. Sobald die Regeln definiert sind, entscheidet das Tool. Das spart Zeit in Code Reviews und verhindert subjektive Diskussionen. Automatische Formatierung vor dem Commit ist eine bewährte Praxis. Sie kann über Pre-Commit Hooks oder direkt im Editor erfolgen. So wird sichergestellt, dass der Code bereits beim Speichern oder vor dem Push den definierten Standards entspricht.

Dokumentation allein reicht jedoch nicht aus. Viele Regeln geraten im Alltag schnell in Vergessenheit, wenn sie nicht regelmäßig angewendet oder reflektiert werden. Pair Programming, gemeinsame Code Reviews oder kurze Teamrunden zur Codequalität helfen dabei, die Regeln im Gedächtnis zu behalten und bei Bedarf weiterzuentwickeln. So entsteht ein gemeinsames Verständnis, das über reine Technik hinausgeht.

In bestehenden Projekten mit Legacy-Code empfiehlt es sich, die Formatierung schrittweise einzuführen. Statt das gesamte Repository auf einmal zu ändern, kann man neue oder geänderte Dateien automatisch formatieren und so nach und nach Vereinheitlichung schaffen.

Fazit

Einheitliche Codeformatierung ist kein Detail, sondern ein zentraler Bestandteil professioneller Softwareentwicklung. Sie verbessert die Lesbarkeit, reduziert Konflikte und spart Zeit bei der Zusammenarbeit im Team. Wer Formatierung automatisiert und konsequent durchsetzt, schafft Klarheit und Verlässlichkeit im Code.

Die Einführung gemeinsamer Regeln lohnt sich besonders dann, wenn sie über einzelne Projekte hinaus gelten. Gemeinsame Konfigurationen, automatisierte Prüfungen und regelmäßiger Austausch im Team sorgen dafür, dass die Regeln nicht nur existieren, sondern auch gelebt werden. Dokumentation ist hilfreich, aber erst durch Tools, Pair Programming und gemeinsame Verantwortung wird Formatierung zur Selbstverständlichkeit.

Wie geht ihr aktuell im Team mit Codeformatierung um und welche Erfahrungen habt ihr mit automatisierten Tools gemacht? Schau gerne bei uns auf LinkedIn vorbei und diskutiere mit.