Auch R markdown Dateien sollten sich an Regeln halten

May 2, 2018 3 min Lesezeit Allgemeines, Information

Jede Programmiersprache hat Regeln. Neben dem Regelwerk welches durch den Syntax einer Sprache festgelegt wird, gib es aber noch Regeln über die Form in der man den Quelltext schreibt. Diese sogenannte Stilregeln (engl. style guides) sind von Programmieren aufgestellte Regeln um ein einheitliches “Schriftbild” des Quelltextes zu erhalten. Das Ziel der Stilregeln ist es, den Quelltext lesbarer zu gestallten, um leichter Änderungen einzupflegen oder um unnötiges zu vermeiden.

Eine Programmiersprache wie Python zum Beispiel hat mit PEP8 einen eigenen Standard wie ein Python Programm geschrieben seien sollte. Dazu gibt es auch gleich das passenden Prüfprogramm (früher pep8, neuerdings pycodestyle).

Schreibt man ein R markdown Text mag man vielleicht nicht daran denken, dass so eine Idee auch hier sehr sinnvoll ist. Neben den gängigen Style-Guides für den R Quellcode (z. B.: Google’s R Style Guide, Hadley Wickham’s Advanced R - Style guide, jef.works R Style Guide, R Style Guide oder R-Style-Guide) gibt es aber kaum Regeln (z. B.: Pimp my Rmd) für die Gestaltung von R markdown.

Stil-Regeln für gutes R markdown, ein erster Vorschlag

  1. Keine unnützen Zeichen am Ende von Textzeilen. / No whitespaces at the end of a line

    Eine Textzeile sollte mit einem ‘echtem’ Zeichen enden und nicht mit einem ‘unsichtbarem’ Zeichen. Das heisst: Leerzeichen, Tabs, harte Leerzeichen etc. gehören nicht ans Ende einer Zeile.

  2. Zwei Leerzeilen vor einer jeden Kopfzeile. / Two blank lines before every header

    Um die Inhalte auch klar voneinander trennen zu können sollte man vor der Kopfzeile zwei Leerzeilen eingefügt werden. Statt

    # Das ist eine Kopfzeile auf der 1. Ebene
## Das is eine Kopfzeile auf der 2. Ebene
Das hier ist einfacher Text

    sollte es so gegliedert sein:

    

# Das ist eine Kopfzeile auf der 1. Ebene


## Das is eine Kopfzeile auf der 2. Ebene

Das hier ist einfacher Text

  3. Vor und nach Aufzählungen sollte immer eine Leerzeile stehen. / One blank line before and after itemizations or enumerations

    Statt

    Das ist eine Liste:
- Ein Punkt
- Ein anderer Punkt
Und hier geht der Text weiter.
1. Der erste Punkt.
2. Der zweite Punkt.
Und wieder mal ein Text.

    sollte es so gegliedert sein:

    Das ist eine Liste:

- Ein Punkt
- Ein anderer Punkt

Und hier geht der Text weiter.

1. Der erste Punkt.
2. Der zweite Punkt.

Und wieder mal ein Text.

  4. Vor und nach Codeblöcken sollte immer eine Leerzeile stehen. / One blank line before and after a codeblock

    Statt

    Etwas Text vorher
```{r}1+1
```und danach.

    sollte man es besser wie folgt gliedern:

    Etwas Text vorher

```{r}1+1
``` und danach.

  5. Keine anderen Sprachen als R markdown für Inhalte oder Design nutzen. / Use no other languages to create content or design, other than (R) markdown.

    Keine anderen Sprachen, insbesondere LaTeX, um besondere Effekte zu erzielen. Dafür sollten (native) DIV oder SPAN Abschnitte benutzt werden und entsprechend durch spätere (Filter-)Programme umgesetzt werden. So ist es immer möglich Design-Ideen für alle möglichen Zielsprachen zu erhalten.

RmdStyleChecker, ein erster Style Checker für R markdown

Die ersten drei Punkte der Liste habe ich zu Testzwecken in einem kleinen Projekt mit Hilfe von Python implementiert. Den Python-Quelltext findet man unter RmdStyleChecker. Er läuft unter Python 3.5+.

R Allgemein R markdown Python
Norman Markgraf
Norman Markgraf
Diplom-Mathematiker

Norman Markgraf ist freiberuflicher Dozent für Mathematik, Statistik, Data Science und Informatik, sowie freiberuflicher Programmierer.

Ähnliches