Konzepte

Konzepte sind die Dinge, die ein Programmierer verstehen muss, um eine Sprache fließend zu beherrschen. Konzepte werden in Konzeptübungen vermittelt und dienen als Voraussetzung für Konzept- und Praxisübungen. Wenn sie den Lernenden angezeigt werden, werden Konzepte auf einer Konzeptkarte platziert.

Metadaten

Die Metadaten eines Konzepts werden im Schlüssel concepts in der config.json-Datei definiert. Die Metadaten definieren unter anderem die UUID und den Slug des Konzepts.

Beispiel

{
  "concepts": [
    {
      "uuid": "b9a421b2-c5ff-4213-bd6d-b886da31ea0d",
      "slug": "numbers",
      "name": "Numbers"
    }
  ]
}

Dateien

Jedes Konzept hat ein eigenes Verzeichnis innerhalb des concepts-Verzeichnisses des Tracks. Der Name des Konzeptverzeichnisses muss mit der Eigenschaft slug des Konzepts übereinstimmen, wie sie in der config.json-Datei definiert ist.

Ein Konzept hat zwei Arten von Dateien:

Dokumentationsdateien

Diese Dateien werden den Lernenden gezeigt, um das Konzept zu erklären.

  • about.md: liefert Informationen über das Konzept für Lernende, die die zugehörige Konzeptübung abgeschlossen haben, zum Lernen und Nachschlagen (erforderlich)
  • introduction.md: bietet eine kurze Einführung für Lernende, die die zugehörige Konzeptübung noch nicht abgeschlossen haben (erforderlich)
  • links.json: liefert hilfreiche Links mit weiterführender Lektüre oder Informationen zu einem Konzept (erforderlich)

Metadatendateien

Diese Dateien werden den Lernenden nicht angezeigt, sondern dienen dazu, die Metadaten des Konzepts zu definieren.

  • .meta/config.json: enthält Meta-Informationen zum Konzept (erforderlich)

Beispiel

concepts
└── numbers
    ├── .meta
    |   └── config.json
    ├── about.md
    ├── introduction.md
    └── links.json

Datei: about.md

Zweck: Ausführlichere Informationen über das Konzept für Lernende, die die zugehörige Konzeptübung abgeschlossen haben, zum Lernen und Nachschlagen.

Vorhandensein: Erforderlich

Nach Abschluss der zugehörigen Konzeptübung (auch als „Lernen“ eines Konzepts bekannt) zeigt die Konzeptseite den Inhalt der about.md-Datei statt der introduction.md-Datei an. Die about.md-Datei sollte den Lernenden umfassende Informationen darüber geben, was sie wissen müssen, um das Konzept fließend zu beherrschen. Mindestens sollte diese Datei alle Informationen enthalten, die in der introduction.md-Datei des Konzepts vorgestellt werden.

Wenn das Konzept neue Syntax einführt, sollten Syntaxbeispiele enthalten sein. Die Lernenden sollten nicht vielen Links folgen müssen, um das Wissen zu erlangen, das die Datei vermitteln soll. Stattdessen sollte die about.md genügend Informationen enthalten, um im jeweiligen Kontext verständlich zu sein.

Die about.md-Datei ist nicht auf den Umfang der zugehörigen Konzeptübung beschränkt. Der Inhalt kann Wissen über andere Konzepte voraussetzen, die erst später eingeführt werden. Wenn andere Konzepte erwähnt werden, sollte auf ihre jeweiligen Einführungen verlinkt werden (siehe interne Verlinkung für Details).

Hier sind einige Beispiele, was behandelt werden könnte.

  • Beliebte Anwendungsfälle für ein Konzept
  • Häufige Fallstricke bei der Verwendung eines Konzepts (z. B. wenn die Thread-Sicherheit nicht bedacht wird)
  • Einschränkungen der Verwendung, die den ahnungslosen Entwickler überraschen können
  • Alternative Ansätze, die in anderen Konzepten behandelt werden (z. B. könnte das Rekursion-Konzept erwähnen, dass das Funktionen höherer Ordnung-Konzept einen alternativen Ansatz für ähnliche Probleme bietet)
  • Kompromisse, die zugunsten der Lernbarkeit oder zur Anpassung an die Exercism-Umgebung eingegangen werden, z. B. mehrere Klassen in einer einzigen Datei
  • Ähnliche Sprachmerkmale, mit denen das Konzept verwechselt werden kann
  • Performance-Eigenschaften und Speicherverbrauch, wenn dies in dieser Sprache üblicherweise eine Rolle spielt
  • Verweise im Text nicht auf eine Übung, denn diese Datei wird außerhalb des Kontexts einer Übung angezeigt.

Es ist nicht das Ziel der about.md-Datei, eine vollständige Sammlung von Informationen über das Konzept zu liefern. Stell dir zum Beispiel eine Sprache vor, die einige ältere Sprachmerkmale hat, von denen erfahrene Programmierer (und vielleicht sogar die offiziellen Docs/Spezifikationen) empfehlen, sie nicht mehr zu verwenden. Details zu solchen Sprachmerkmalen zu liefern, läge außerhalb des Rahmens der about.md-Datei, denn sie sind nicht relevant, um fließende Beherrschung zu erlangen. Maintainer können jedoch beschließen, einen kurzen Abschnitt hinzuzufügen, der die alten Standards erwähnt, falls Lernende häufig in freier Wildbahn auf diese Standards stoßen. Dieser Abschnitt sollte aber als solcher gekennzeichnet sein.

Die about.md-Datei MUSS klar strukturiert sein, besonders wenn sie viele Informationen enthält. In Zukunft wird es außerdem die Möglichkeit geben, Teile als „fortgeschrittene Themen“ zu markieren, um interessierte Lernende darauf hinzuweisen, ohne andere zu überlasten.

Beispiel

# About

There are two different kinds of numbers in Elixir - integers and floats.

Floats are numbers with one or more digits behind the decimal separator. They use the 64-bit double precision floating-point format.

```elixir
float = 3.45
# => 3.45
```

Elixir also supports the scientific notation for floats.

```elixir
1.25e-2
# => 0.0125
```

## Rounding errors

Floats are infamous for their rounding errors.

```elixir
0.1 + 0.2
# => 0.30000000000000004
```

However, those kind of errors are not specific to Elixir. They happen in all programming languages. This is because all data on our computers is stored and processed as binary code. In binary, only fractions whose denominator can be expressed as `2^n` (e.g. `1/4`, `3/8`, `5/16`) can be expressed exactly. Other fractions are expressed as estimations.

```elixir
# 3/4
Float.ratio(0.75)
# => {3, 4}

# 3/5
Float.ratio(0.6)
# => {5404319552844595, 9007199254740992}
```

You can learn more about this problem at [0.30000000000000004.com][0.30000000000000004.com]. The [Float Toy page][evanw.github.io-float-toy] has a nice, graphical explanation how a floating-point number's bits are converted to an actual floating-point value.

Datei: introduction.md

Zweck: Bietet eine kurze Einführung für Lernende, die die zugehörige Konzeptübung noch nicht abgeschlossen haben.

Vorhandensein: Erforderlich

Diese Datei wird angezeigt, wenn Lernende die zugehörige Konzeptübung noch nicht abgeschlossen haben. Sie sollte eine kurze Einführung in das Konzept bieten.

  • Es sollten nur Informationen bereitgestellt werden, die nötig sind, um die Grundlagen des Konzepts zu verstehen. Zusätzliche Informationen gehören in die about.md-Datei.
  • Links sollten sparsam eingesetzt werden, wenn überhaupt. Ein Link, der ein komplexes Thema wie Rekursion erklärt, mag nützlich sein, doch bei den meisten Konzepten liefern die Links mehr Informationen als nötig. Ziel sollte es daher sein, die Dinge knapp direkt im Text zu erklären.
  • Es sollten die richtigen Fachbegriffe verwendet werden, damit die Lernenden leicht nach weiteren Informationen suchen können.
  • Codebeispiele sollten nur verwendet werden, um neue Syntax einzuführen (Lernende sollten nicht im Web nach Syntaxbeispielen suchen müssen). In anderen Fällen gib stattdessen Beschreibungen oder Links an.
  • Verweise im Text nicht auf eine Übung, denn diese Datei wird außerhalb des Kontexts einer Übung angezeigt.

Beispiel

# Introduction

One of the key aspects of working with numbers in C# is the distinction between integers and floating-point numbers (numbers with zero or more digits after the decimal separator).

The two most commonly used numeric types in C# are `int` (a 32-bit integer) and `double` (a 64-bit floating-point number).

```csharp
int i = 123;
double d = 54.29;
```

Zweck: Bietet hilfreiche Links mit weiterführender Lektüre oder Informationen zu einem Konzept.

Vorhandensein: Erforderlich

Das können offizielle Docs sein, ein gutes Tutorial usw. Diese Links ersetzen nicht die kontextbezogeneren Links in der about.md-Datei eines Konzepts, sondern bieten den Lernenden eine schnelle Sammlung übergreifender Anlaufpunkte.

Jeder Link muss die folgenden Felder enthalten:

  • url: die URL, auf die verwiesen wird.
  • description: eine Beschreibung des Links, die als Linktext angezeigt wird.

Links können außerdem optional ein Feld icon_url haben, mit dem sich das Symbol anpassen lässt, das bei der Anzeige des Links erscheint. Wird es nicht angegeben, wird standardmäßig das Favicon verwendet.

[
  {
    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/intro-to-csharp/numbers-in-csharp-local",
    "description": "Numbers in C#"
  },
  {
    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/integral-numeric-types",
    "description": "Integral numeric types",
    "icon_url": "http://test.org/icon.png"
  }
]

Datei: .meta/config.json

Zweck: Enthält Meta-Informationen zum Konzept.

Vorhandensein: Erforderlich

Diese Datei enthält Meta-Informationen zum Konzept:

  • authors: Die GitHub-Benutzernamen der Autoren des Konzepts (erforderlich)
    • Einschließlich der Reviewer, wenn ihre Reviews das Konzept wesentlich verändern (so sehr, dass es sich anfühlt, als hättet ihr es gemeinsam erarbeitet)
  • contributors: Die GitHub-Benutzernamen der Mitwirkenden des Konzepts (optional)
    • Einschließlich der Reviewer, wenn ihre Reviews aussagekräftig, umsetzbar oder umgesetzt sind.
  • blurb: Eine kurze Beschreibung dieses Konzepts. Die Länge muss <= 350 sein. Markdown wird nicht unterstützt (erforderlich)

Ist jemand sowohl Autor als auch Mitwirkender, führe diese Person nur als Autor auf.

Beispiel

{
  "authors": ["FSharpForever"],
  "contributors": ["IWantToHelp"],
  "blurb": "F# has two types of numbers: integers and floating-point numbers."
}

Beachte:

  • Die Reihenfolge von Autoren und Mitwirkenden spielt keine Rolle und hat keine Bedeutung.