Analyzer-Kommentare schreiben

Dieses Dokument enthält Informationen und Leitlinien dazu, wie du Kommentare schreibst, die vom Analyzer erzeugt werden.

Inhalt

Die Inhalte für Analyzer-Kommentare sind als Markdown-Dokument im Repo exercism/website-copy gespeichert. Kommentare enthalten einen Verweis-String im Format <track-slug>.<exercise-slug>.<comment-slug>, der auf ein bestimmtes Markdown-Dokument im website-copy-Repo verweist.

Zum Beispiel verweist ruby.two-fer.string-interpolation auf https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md.

Formulierung

• Vermeide unnötig wortreiche Kommentare. Fasse dich kurz.
• Beobachte neutral und vermeide wertende und pauschale Aussagen.
• Formuliere die Empfehlung explizit.
• Stelle wenn möglich die Empfehlung an den Anfang und die Erklärung danach.
• Vermeide „ich“, „wir“ usw., denn der Bot ist keine Person.
• Vermeide „du“ und „dein Code“, denn das kann manchmal so wirken, als würde die Person statt des Codes beurteilt.
• Vermeide Wörter wie „nur“, „einfach“, „offensichtlich“, die herablassend wirken können: Wenn der Kommentar nötig ist, war er offensichtlich nicht offensichtlich.
• Gehe nicht davon aus, was Menschen wissen und was nicht. Die einzige Ausnahme ist Wissen aus bereits abgeschlossenen Kern-Übungen. Vermeide „wie du weißt“, „wie du dich erinnerst“, „wie du gelernt hast“, „jetzt, wo wir alle x verstehen“, denn auch wenn etwas gesagt wurde, heißt das nicht, dass die Person es versteht.

Leitlinien

• Strebe Geläufigkeit an, nicht Beherrschung: Das Ziel eines Sprach-Tracks auf Exercism ist es, Menschen einen Weg zu geben, ein hohes Maß an Geläufigkeit bei einem geringen Maß an Beherrschung zu erreichen. Wir streben Geläufigkeit in der Syntax, den Idiomen und der Standardbibliothek der Sprache an.
• Empfiehl idiomatischen Code, wenn möglich; idiomatisch ist Code, den fast alle Entwickler (keine Hobbyisten) schreiben würden, die in dieser Sprache programmieren. Wenn du einen nicht-idiomatischen Vorschlag machst, erwähne das und erkläre, warum der Vorschlag trotzdem nützlich sein kann.
• Benenne den Unterschied zwischen dem, was die Person macht, und dem, was in der Sprache als ‚idiomatisch‘ gilt.
• Verwende die richtigen Begriffe und Bezeichnungen, damit Menschen diese Konzepte auch anderswo wiedererkennen und selbst dazu recherchieren können.
• Verrate nicht die Lösung als allgemeinen Ratschlag für jedes Mentoring auf Exercism. Lernen bleibt hängen, wenn Menschen die Antwort selbst entdecken. Das ist ein ungemein beflügelndes Erlebnis, und der emotionale Kick macht es einprägsam. Wenn die Entdeckung jedoch keinen Dopaminschub auslöst, ist es völlig sinnvoll, zu zeigen, wie es aussieht. Zum Beispiel ist ein kleiner Verbesserungsvorschlag zu einer akzeptierten Lösung deutlich weniger spannend, als jemandem zu einer abgelehnten Lösung einen Lernpunkt zu geben. Letzteres rechtfertigt daher eher ein Beispiel als einen Link.
• Ordne die Kommentare nach Wichtigkeit, wobei der erste Kommentar der wichtigste und der letzte der unwichtigste ist.
• Halte die Anzahl der Kommentare überschaubar. Strebe ein bis drei Kommentare pro Iteration an.
• Füge denselben Kommentar nicht zweimal in einer Analyse hinzu. Denselben Kommentar mit unterschiedlichen Parametern hinzuzufügen gilt nicht als Duplikat.
• Kommentiere nur dann die Formatierung, wenn Formatierung oder Linting fester Bestandteil der Sprache sind. Weise Lernende wenn möglich auf Tools zur automatischen Formatierung hin und/oder verlinke den offiziellen Styleguide.

Die ersten Übungen

Für die ersten Übungen eines Tracks ist Folgendes besonders wichtig:

• Halte dich eher kurz und vermeide eine Textwand oder überhäufe sie nicht mit Ratschlägen. Wenn ihnen die erste Übung Freude macht, kommen sie wieder, und du hast viel mehr Gelegenheiten, Rückmeldung zu all den Dingen zu geben, die dir aufgefallen sind.
• Erkläre ein Konzept nicht zu ausführlich: Geh nicht ins Detail bei den zugrunde liegenden Mechanismen von Compilern und Ähnlichem. Hier geht es eher darum, dass dies eine der ersten Übungen im Sprach-Track ist, und in dieser Phase hilft Rückmeldung mehr, wenn sie kürzer und direkter ist.
• Gib einen Link an, der genau zeigt, wie man das Konzept umsetzt, und zwar im Stil eines Tutorials. Das heißt: zeigen, wie man etwas macht, nicht, warum. Das kann bedeuten, dass die offizielle Dokumentation der Sprache nicht ausreicht, denn diese ist oft eine Code-Referenz und zeigt dir nicht, wie man sie benutzt und wie sie funktioniert. Allerdings solltest du einen Link nur für eine tiefergehende Erkundung angeben. Die Person sollte direkt aus der Antwort verstehen können, was du meinst, ohne dem Link zu folgen.

Beispiele

In JavaScript hat eine lernende Person eine Konstante auf oberster Ebene mit let geschrieben.

<!-- not following these guidelines -->

As you know, everyone uses const, you shouldn't use let or var.

Dieser Kommentar folgt aus den folgenden Gründen nicht diesen Leitlinien:

• Die Handlung kommt nach der „Erklärung“.
• „As you know“: Wir wissen nicht, ob die lernende Person das tatsächlich weiß.
• „you shouldn't“: Du brauchst das „you“ nicht, um diese Aussage zu machen.
• „everyone uses const“: Das stimmt nicht und kann bei der lernenden Person den Eindruck erwecken, sie hätte etwas furchtbar falsch gemacht.
• Es fehlt eine tatsächliche Erklärung dafür, warum der Ratschlag gegeben wird.

<!-- better -->

Prefer `const` and `let` over `var`. The `const` declaration stops a variable
from being accidentally reassigned, which provides safety, and reduces
cognitive load for someone reading the code. [This article](https://medium.com/javascript-scene/javascript-es6-var-let-or-const-ba58b8dcde75)
explains the difference between the three.

In Go hat eine lernende Person einen eigenen Fehler erstellt, anstatt die eingebauten zu verwenden:

<!-- not following these guidelines -->

I see you are creating a custom `error`. This is perfectly fine! If you did not
know about `errors.New` and `fmt.Errorf` have a look at them as they are much
simpler ways to create an error. Custom errors are helpful if you want to check
if an error is of a certain type later.

Dieser Kommentar folgt aus den folgenden Gründen nicht diesen Leitlinien:

• „I see“: Der Analyzer ist keine Person: Vermeide „I“.
• „This is perfectly fine!“: Wäre es das, wäre die Beschwichtigung nicht nötig gewesen. Das kann man wahrscheinlich ganz weglassen; wenn du einen allgemeinen Tipp zu etwas geben willst, das es gibt, kannst du genau das sagen: „Eine alternative, ebenso gültige Möglichkeit, x zu tun, ist y.“
• „If you did not know about“: Lass diese übermäßig wortreiche Wortgruppe weg.

<!-- better -->

A custom `error` is typically used to provide custom behavior, or to distinguish
on type later. For simpler cases, it's more common to rely on `errors.New` or
`fmt.Errorf`. This [in-depth article](https://golangbot.com/custom-errors/) about
custom errors might be interesting.

CI

Da die Kommentare nicht im selben Repository wie der Analyzer liegen, sollte jeder Analyzer eine CI haben, die prüft, ob die in diesem speziellen Analyzer verwendeten Kommentare (also die, die zur Ausgabe werden können) Kommentare im main-Branch des Repositorys exercism/website-copy sind.

Zum Zeitpunkt des Schreibens verfolgt dieses Issue den Status einer eventuellen Verallgemeinerung dieser CI.