Exercism-Styleguide

Dieses Dokument ist der Styleguide für die Sprache und die Formulierungen, die in Übungen verwendet werden.

Anwendung

Diese Regeln sollten in allen Übungen befolgt werden. Bestehende Beschreibungen und Testfälle können so aktualisiert werden, dass sie diesen Regeln entsprechen; es sind keine „Ersatz“-Testfälle erforderlich.

Einheitlichkeit innerhalb einer Übung

Manche Begriffe haben mehrere gültige Schreibweisen (z. B. „lower case“ vs. „lowercase“). Wo in diesem Dokument kein einheitlicher Stil festgelegt wurde, müssen sie innerhalb einer Übung einheitlich geschrieben werden.

Ausnahmen

Übungen dürfen von diesen Regeln abweichen, wenn unter den Maintainern allgemeiner Konsens besteht, dass das sinnvoll ist. Eine Übung zum Umrechnen zwischen verschiedenen Einheiten könnte zum Beispiel bewusst darauf verzichten, SI-Maße zu verwenden.

Sprache

Alle Inhalte sollten in US-Englisch geschrieben werden, das sich in vielfältiger Weise vom britischen Englisch unterscheidet. Künftig wird es vielleicht weitere Übersetzungen geben, aber die „offizielle“ Sprache von Exercism ist US-Englisch.

Maßeinheiten

Alle Maßeinheiten müssen SI-Einheiten oder von SI abgeleitete Einheiten sein.

Abkürzungen, Akronyme und Initialwörter

Abkürzungen, Akronyme und Initialwörter sind oft schwerer zu verstehen als andere Formulierungen und können Menschen, die gerade lernen, abschrecken.

Viele Abkürzungen sind Fachjargon. Vermeide Jargon, wo es geht, indem du andere Formulierungen verwendest. Verwende eine Abkürzung nur, wenn eine der beiden Bedingungen zutrifft:

  • Die abgekürzte Bezeichnung ist bekannter als die ausgeschriebene
  • Der Text würde ohne die Abkürzung übermäßig weitschweifig

Wenn du eine Abkürzung verwendest, erkläre immer beim ersten Auftreten, was der Begriff bedeutet. Das bedeutet oft, aber nicht immer, dass du die Abkürzung ausschreibst. Es reicht nur selten aus, die Abkürzung bloß auszuschreiben.

Hier sind einige Beispielregeln:

  • Verwende lieber „if I recall correctly“ als „IIRC“
  • Verwende lieber „as far as I know“ als „AFAIK“
  • Verwende lieber „queue“ als „FIFO“ und „stack“ als „FILO“
  • Beschreibe eine Schnittstelle lieber über ihre konkreten Eigenschaften, statt sie als „RESTful“ zu bezeichnen
  • Wenn du „CRUD“ verwenden musst, erkläre, dass es für Create, Read, Update, Delete steht und dass das die grundlegenden Aktionen in Standarddatenbanken sind

Und einige Beispiele für eine gute Verwendung:

  • „HyperText Markup Language (HTML) is the language used to describe document structure and content on the web“ (ausgeschrieben und erklärt)
  • „DNA, a set of chemical instructions that influence how our bodies are constructed“ (DNA wird nicht ausgeschrieben, weil „deoxyribonucleic acid“ unserem Publikum kaum dabei hilft, zu erklären, was DNA ist)
  • „NASA, the United States' space agency, launched the Mariner 2 space probe in...“ (NASA wird nicht ausgeschrieben, weil die „National Aerospace and Space Administration“ unter ihrer Abkürzung viel bekannter ist als unter ihrem ausgeschriebenen Namen)
  • „The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV“ (DMV wird beim ersten Auftreten definiert)

Grammatik

Oxford-Komma

Verwende in Aufzählungen das Oxford-Komma (auch als serielles Komma bekannt). Schreibe zum Beispiel statt „I love my parents, Lady Gaga and Humpty Dumpty“ lieber „I love my parents, Lady Gaga, and Humpty Dumpty“. Vielleicht gefällt dir auch dieses Bild als Erklärung.

Ausnahmen

Einige Abkürzungen gelten als so gebräuchlich, nützlich und untechnisch, dass wir entschieden haben, sie zuzulassen:

  • e.g. oder eg
  • i.e. oder ie
  • etc. oder etc
  • docs

Kontraktionen (z. B. „won't“, „I'm“, „that's“) solltest du in Übungsbeschreibungen sparsam oder gar nicht verwenden; an anderen Stellen rund um die Website (z. B. in Website-Texten oder beim Mentoring) sind sie nicht eingeschränkt.

Viele amerikanische Styleguides geben an, dass auf die Abkürzungen „i.e.“ und „e.g.“ ein Komma folgen sollte (siehe z. B. diesen StackExchange-Thread). Auf Exercism ist das erlaubt, aber nicht vorgeschrieben.

Wortwahl

Mathematische Begriffe und Fachjargon

Wo immer mathematische Begriffe verwendet werden, sollten sie erklärt oder durch Begriffe ersetzt werden, die weniger Fachwissen voraussetzen.

Beispiele:

  • Statt „natural numbers“ sollten wir „positive whole numbers“ verwenden.
  • Wenn wir den Ausdruck „rational numbers“ verwenden wollen, muss er in der Einleitung zur Übung erklärt werden.
  • Statt des Wortes range (das je nach Kontext unterschiedliche Bedeutungen haben kann) verwende „x < ? < y (greater than x and less than y)“.
  • Statt „esoteric terms“ verwende den Ausdruck „terms not understood by the majority of people“.

Code

Code sollte durchgängig nach den Stilkonventionen des jeweiligen Tracks formatiert sein. Wo möglich sollten diese trackweiten Konventionen mit den bevorzugten Stilkonventionen der Sprache übereinstimmen.