R Language
Meta: Dokumentationsrichtlinien

Bemerkungen

Gute Beispiele machen

Die meisten Anleitungen zum Erstellen guter Beispiele für Fragen und Antworten werden in die Dokumentation übernommen.

• Machen Sie es minimal und kommen Sie auf den Punkt. Komplikationen und Abschweifungen sind kontraproduktiv.

• Fügen Sie sowohl Arbeitscode als auch Prosa zum Erläutern hinzu. Keines reicht alleine aus.

• Verlassen Sie sich nicht auf externe Datenquellen. Generieren Sie Daten oder verwenden Sie nach Möglichkeit die Datensatzbibliothek:

  library(help = "datasets")
  

Es gibt einige zusätzliche Überlegungen im Zusammenhang mit Dokumenten:

• ?data.frame Sie sich auf eingebaute Dokumente wie ?data.frame wenn dies relevant ist. Die SO-Dokumente sind kein Versuch, die integrierten Dokumente zu ersetzen. Es ist wichtig sicherzustellen, dass neue R-Benutzer wissen, dass die integrierten Dokumente vorhanden sind, und wie sie zu finden sind.

• Verschieben Sie den Inhalt, der für mehrere Beispiele gilt, in den Abschnitt "Anmerkungen".

Stil

Eingabeaufforderungen

Wenn Sie möchten, dass Ihr Code kopierfähig ist, entfernen Sie am Anfang jeder neuen Zeile Eingabeaufforderungen wie R> , > oder + . Einige Autoren von Texten ziehen es vor, das Kopieren nicht einfach zu machen, und das ist in Ordnung.

Konsolenausgabe

Die Konsolenausgabe sollte klar vom Code unterschieden werden. Gängige Ansätze sind:

• Einfügen von Eingabeaufforderungen bei der Eingabe (wie bei Verwendung der Konsole zu sehen).
• Kommentieren Sie alle Ausgaben aus, wobei # oder ## jeder Zeile stehen.
• Drucken Sie in der vorliegenden Form und vertrauen Sie der führenden [1] , um die Ausgabe von der Eingabe abzuheben.
• Fügen Sie zwischen Code und Konsolenausgabe eine Leerzeile hinzu.

Zuordnung

= und <- sind gut für die Zuordnung von R-Objekten. Verwenden Sie Leerzeichen entsprechend, um das Schreiben von Code zu vermeiden, der schwer zu analysieren ist, z. B. x<-1 (mehrdeutig zwischen x <- 1 und x < -1 ).

Code-Kommentare

Stellen Sie sicher, dass Sie den Zweck und die Funktion des Codes selbst erklären. Es gibt keine feste Regel, ob diese Erklärung in Prosa oder Code-Kommentaren enthalten sein sollte. Prosa ist möglicherweise lesbarer und erlaubt längere Erklärungen, aber Code-Kommentare erleichtern das Einfügen von Text. Denken Sie an beide Optionen.

Abschnitte

Viele Beispiele sind kurz genug, um keine Abschnitte zu benötigen. Wenn Sie sie jedoch verwenden, beginnen Sie mit H1 .