Einfaches Englisch

Was macht Einfaches Englisch?

Sag die Hauptsache in so wenigen gewöhnlichen Worten wie nötig und hör auf. Der Leser öffnet den Code für die Details.

Sei knapp

• Führe mit dem Punkt ein: was das Ding tut und warum, wenn das nicht offensichtlich ist.
• Lass weg, was der Code oder Diff bereits zeigt: die berührten Dateien, die Reihenfolge der Schritte, die Grenzfälle, die der Code behandelt.
• Verwende den kompakten Ausdruck des Fachs: „unbenutzte Icons entfernen“, nicht „die Icons entfernen, die nichts benutzt“.
• Sag eine Tatsache einmal.
• Streiche Wörter, nicht Fakten. Behalte jeden Schritt, den der Leser braucht, um das Problem zu sehen, und nenne die Konsequenz: „Dieses Datum kann vom Tag abweichen, an dem CI das Release erstellt“, nicht „die Überschrift wird vor dem Release-Tag geschrieben“.

Bleib klar

Knapp ist nicht kryptisch.

• Schreibe einen Gedanken pro Satz, mit Subjekt und Verb. Keine Semikolons, Rätsel oder Slogans wie „kein Release, kein Typ“.
• Setze das Subjekt an den Anfang und nenne, wer handelt: „C++ berechnet X“, nicht „X wird in C++ berechnet“.
• Verwende einfache Zeitformen und das Präsens für das, was noch zutrifft: „QML wertet Bindungen darauf nie neu aus“, nicht „wurden nie neu ausgewertet“.
• Schreibe eine Bedingung als Wenn X, dann Y.
• Wiederhole das Nomen statt „es“, „sie“ oder „diese“, wenn das Nomen einen Satz zurückliegt oder wenn mehrere Nomen infrage kommen.
• Halte „welche“- und „deren“-Nebensätze kurz. Hat der Nebensatz ein eigenes langes Subjekt, schreibe einen eigenen Satz: „Debian- und Ubuntu-Qt-Pakete haben es nicht“, nicht „, welche die Debian- und Ubuntu-Qt-Pakete auslassen“.
• Sage eine Verneinung klar: „Werte außerhalb des Bereichs ignorieren“, nicht „keinen Wert über den Bereich hinaus annehmen“. Verneine nicht über das Objekt: „Die Bearbeitung hat updated() nicht ausgelöst“, nicht „Die Bearbeitung hat kein updated() ausgelöst“. Schreibe „noch“ nur nach „weder“.

Klinge natürlich

Der Text muss sich wie etwas lesen, das ein englischsprachiger Entwickler geschrieben hat. Wenn ein Satz wie eine Übersetzung klingt, schreibe ihn um, selbst wenn die Umformulierung ein Wort länger ist.

• Verwende zusammengesetzte Nomen, keine Ketten von „of“: „app settings“, „the CSV file dialog“, „Debian and Ubuntu Qt packages“. Verwende einen Possessiv nur, wenn keine Zusammensetzung funktioniert, z. B. „the sheet’s density“, und niemals zwei hintereinander. Erlaube höchstens ein „of“ pro Satzteil.
• Verwende das übliche Verb des Fachs: „show“, „report“, „fix“, „support“, „handle“, „check“. Mach Code nicht zu einer Person, die erzählt, antwortet oder trägt. Behalte „own“ für Besitz im C++-Sinne.
• Verwende ein Wort pro Konzept: wähle „check“ oder „verify“, „settings“ oder „options“, und bleib dabei.
• Wiederhole den Artikel nicht in einer Aufzählung: „the frame and delete button“.
• Schreibe „must“ für eine Anforderung und „can“ für eine Möglichkeit. Vermeide „should“, „may“ und „might“.
• Schreibe „for example“, nicht „e.g.“. Verwende amerikanische Rechtschreibung.
• Streiche diese Wörter: „leverage“ und „utilize“ (schreibe „use“), „in order to“ (schreibe „to“), „prior to“ (schreibe „before“), „ensure“, „simply“, „just“, „easily“, „seamlessly“, „robust“, „powerful“, „comprehensive“, „functionality“, „it is worth noting that“, „with this change“, „is designed to“, „allows you to“ (nenn das Ding und sein Verb), „under the hood“, „out of the box“.

Vorher und nachher, aus echten Commit-Betreffen:

Vorher	Nachher
keep the settings of the app out of documents	don’t save app settings in documents
Graph: tell the reader when an export fails	Graph: report export errors
add CardButton, the icon button of the top row of an object	add CardButton, the icon button on an object’s top row
Sampler: take no value of a discrete object past its range	Sampler: ignore discrete object values outside the range
stop a full release whose notes carry another day	check the date in the release notes before a full release
build on Ubuntu 26.04, with its packages of Qt	build on Ubuntu 26.04, with its Qt packages

Nach Textart

Commit-Nachricht

• Schreibe den Betreff als kurzen Imperativ, der auch ohne Diff Sinn ergibt: „limit document values to the settings panel bounds“, nicht „keep the numbers of a document within the range of the panel“.
• Ein Commit tut eine Sache. Wenn der Textkörper ein zweites Thema braucht, teile den Commit.
• Beginne den Textkörper mit dem, was der Code jetzt tut, dann ein kurzes Warum.
• Markiere eine Tatsache jenseits des Betreffs mit „also“: „Both reads also skip unknown keys, because newer versions can add some.“
• Lass Hintergrundwissen weg, das der Leser kennt. Erzähle den Diff nicht neu und verteidige die Änderung nicht.

Code-Kommentar

• Schreibe standardmäßig keinen. Schreibe einen für einen Grund, den der Code nicht zeigt, eine versteckte Invariante oder einen Workaround.
• Sag, was der Code tut, was daraus folgt und warum, einen kurzen Satz pro Teil. Überspringe einen Teil, den der Code bereits zeigt.
• Nenne die API und verwende keine Metaphern. Der Imperativ ist in Ordnung: „skip identical writes: they still update the mtime“.
• Schreibe den Kommentar, den du einem Kollegen geben würdest, der fragt „warum ist das hier?“. Nenne den konkreten Effekt, z. B. „xmin stays on the left“, nicht eine Zusammenfassung wie „the bounds sit where they are“.

Beispiele:

• Vorher: // a vertical list keeps its width a secret, so the style paints a stray handle
• Nachher: // a vertical ListView leaves contentWidth at -1, which the style renders as a collapsed handle
• Vorher: # the runner's glib and libsystemd need its new glibc, so the AppImage uses the host's glib and libdbus. linuxdeploy still copies the libraries that only they need, so the list names those too
• Nachher: # don't bundle glib, libdbus and their dependencies. The AppImage then loads the host's versions. The Ubuntu 26.04 versions need glibc 2.43, which older distros lack.

Dokumentation

• Beschreibe, was der Code heute tut. Nenne das Ding und wofür es ist, und verweise auf die Datei mit den Details.
• Setze drei oder mehr parallele Punkte in eine Aufzählungsliste.
• Setze Stil-, Modul- und Bezeichnernamen in Backticks: FluentWinUI3.
• Markiere eine Tatsache über Drittanbieter-Software, die sich ändern kann, mit „currently“ oder der Version: „Debian and Ubuntu Qt packages currently don’t have it.“

Fehlermeldung: Was passiert ist, die Ursache, falls bekannt, und was zu tun ist. Keine Entschuldigung.

Tooltip: Was das Widget setzt.

Anweisungen für einen Agenten: Eine Regel pro Satz, die Bedingung zuerst.

In Ruhe lassen

Code, Bezeichner, Befehle, Pfade, zitierte Nachrichten, Produktnamen und die Namen von Schaltflächen, Tabs, Feldern und Menüeinträgen.

Vor der Auslieferung

Lies den Text einmal als sein Leser. Streiche jeden Satz, der diesem Leser nicht hilft. Prüfe, dass jeder verbliebene Satz auf Anhieb richtig gelesen wird und wie übliches Englisch klingt.

Wenn du denselben Sachverhalt im Chat erklärt hast, vergleiche die beiden. Wenn die Chat-Version klarer ist, verwende sie.