scientificComputing/codestyle/lecture/codestyle_de.tex

\chapter{\tr{Programming style}{Programmierstil}}

\shortquote{Any code of your own that you haven't looked at for six or
  more months might as well have been written by someone
  else.}{Eagleson's law}

\selectlanguage{ngerman}

Guter Programmierstil ist keine Frage des guten Geschmacks sondern des
Verst\"andnisses von Programmcode und ein Baustein in dem Bestreben
wissenschaftlichen Erkenntnisgewinn reproduzierbar zu
machen. 

Programme sollten so geschrieben und strukturiert sein, dass es sowohl
einem Au{\ss}enstehenden als auch einem selbst --- nach ein paar
Wochen oder Monaten! --- leicht f\"allt den Programmablauf
nachzuvollziehen und zu verstehen. Saubere Programmierung zahlt sich
in erster Linie f\"ur einen selbst aus und macht es aber gleichzeitig
f\"ur andere Personen leichter, den Code nachzuvollziehen und zu
benutzen.

Guter Programmierstil greift auf unterschiedlichen Ebenen an:
\begin{enumerate}
\item Die Dateistruktur von Programmen.
\item Die Namensgebung von Skripten und Funktionen.  
\item Die Namensgebung f\"ur Variablen und Konstanten.
\item Die Verwendung von Einr\"uckungen und Leerzeilen um Bl\"ocke im
  Code hervorzuheben.
\item Verwendung von Kommentaren und Hilfetexten.
\item Auslagerung von Funktionalit\"at in eigene Funktionen.
\end{enumerate}

\section{Organisation von Programmdateien im Dateisystem}

In der Einf\"uhrung zu Funktionen und Skripten wurde schon einmal ein
typisches Programmlayout vorgestellt (box\,\ref{whenscriptsbox}). Hier
wurde vorgeschlagen ein Skript als Kontrollskript zu verwenden. Dieses
kontrolliert den weiteren Programmablauf, ruft Funktionen auf,
\"ubergibt Argumente und nimmt R\"uckgabewerte entgegen. Eine solche
Struktur macht es einfach den Ablauf zu verstehen. Es bleibt aber die
Frage, wie man das Kontrollskript unter den anderen \codeterm{m-files}
als solches erkennt. Um dieses zu erleichtern gilt es zwei Dinge zu
beachten: (i) Wie werden Programme im Dateisystem organisiert? (ii) Wie
werden Programme benannt?

Es hilft ungemein, wenn zusammengeh\"orige Skripte und Funktionen im
gleichen Ordner auf der Festplatte zu finden sind. Es bietet sich also
an, f\"ur jede Analyse einen eigenen Ordner anzulegen und in diesem
die zugeh\"origen \codeterm{m-files} abzulegen. Auf eine tiefere
Schachtelung in weitere Unterordner kann in der Regel verzichtet
werden. \matlab{} erzeugt einen ``MATLAB'' Ordner im eigenen
\file{Documents} (Linux) oder \file{Eigene Dokumente} (Windows)
Ordner. Es bietet sich an, diesen Ordner als Wurzelverzeichnis f\"ur
eigene Arbeiten zu verwenden. Nat\"urlich kann auch jeder andere Ort
gew\"ahlt werden. In dem Beispiel in \figref{fileorganizationfig} wird
innerhalb dieses Ordners f\"ur jedes Projekt ein eigener Unterordner
erstellt, in welchem wiederum f\"ur jedes Problem, jede Analyse ein
weiterer Unterodner erstellt wird. In diesen liegen sowohl die
ben\"otigten \codeterm{m-files} also auch die Resultate der Analyse
(Abbildungen, Daten-Dateien). Zu bemerken sind noch zwei weitere
Dinge. Im Projektordner existiert ein Skript (analysis.m), das dazu
gedacht ist, alle Analysen aufzurufen. Des Weiteren gibt es parallel
zu den Projektordnern einen \file{functions}-Ordner in dem Funktionen
liegen, die in mehr als einem Projekt oder einer Analyse gebraucht
werden.

Beim Betrachten dieses Layouts f\"allt auf, dass es sehr
wahrscheinlich ist, dass bestimmte Namen f\"ur Funktionen und Skripte
mehrfach verwendet werden. Es ist nicht verwunderlich, wenn eine
\file{load\_data.m} Funktion in jeder Analyse vorkommt. In der Regel
wird dies nicht zu Konflikten f\"uhren, da \matlab{} zuerst im
aktuellen Ordner nach passenden Dateien sucht (mehr Information zum
\matlab-Suchpfad in Box~\ref{matlabpathbox}).

\begin{figure}[tp]
  \includegraphics[width=0.75\textwidth]{program_organization}
  \titlecaption{\label{fileorganizationfig} M\"ogliche Organisation von
    Programmcode im Dateisystem.}{ F\"ur jedes Projekt werden
    Unterordner f\"ur die einzelnen Analysen angelegt. Auf Ebene des
    Projektes k\"onnte es ein Skript (hier ``analysis.m'') geben,
    welches alle Analysen in den Unterordnern anst\"o{\ss}t.}
\end{figure}


\begin{ibox}[tp]{\label{matlabpathbox}Der \matlab{} Suchpfad}
  Der Suchpfad definiert, wo \matlab{} nach Skripten und Funktionen
  sucht. Wird eine Funktion aufgerufen wird zun\"achst im aktuellen
  Arbeitsverzeichnis einem Treffer gesucht. Schl\"agt diese Suche
  fehl, so arbeitet sich \matlab{} durch den \codeterm{Suchpfad}
  (siehe Abbildung). Der \codeterm{Suchpfad} ist eine Liste von
  Ordnern in denen \matlab{} nach Funktionen und Skripten suchen
  soll. Die Suche nach der aufgerufenen Funktion wird dabei von oben
  nach unten durchgef\"uhrt. Das heisst, dass es bei
  Namensgleichheit eine Rolle spielen kann an welcher Stelle im
  Suchpfad der erste Treffer gefunden wird. Wichtig: \matlab{} sucht
  nicht rekursiv! Wenn die gew\"unschte Funktion in einem Unterordner
  des aktuellen Arbeitsverzeichnisses liegt, dieses aber nicht
  explizit im Suchpfad enthalten ist, so wird die Funktion nicht
  gefunden.

  \vspace{2ex}
  \includegraphics[width=0.9\textwidth]{search_path}
  \vspace{1.5ex}

  Der Suchpfad kann sowohl \"uber die Kommandozeile mit dem Kommandos
  \code{addpath()} und \code{userpath()} als auch\"uber die in der
  Abbildung gezeigte GUI angezeigt und eingestellt werden. Die GUI
  erlaubt Ordner aus dem Suchpfad zu entfernen, neue Ordner (optional
  inklusive aller Unterordner) hinzuzuf\"ugen oder die Reihenfolge der
  Pfade zu ver\"andern.

  Zum Wechseln des aktuellen Arbeitsverzeichnisses wird das Kommando
  \code{cd} verwendet. \code{which} zeigt an, in welchem Pfad eine
  bestimmte Funktion gefunden wurde. Das aktuelle Areitsverzeichnis
  wird durch den Aufruf \code{pwd} auf der Kommandozeile ausgegeben.
\end{ibox}

\section{Namensgebung von Funktionen und Skripten}

\matlab{} sucht Funktionen und Skripte ausschlie{\ss}lich anhand des
Namens. Dabei spielt die Gro{\ss}- und Kleinschreibung eine Rolle. Die
beiden Dateien \file{test\_funktion.m} und \file{Test\_Funktion.m}
zwei unterschiedliche Funktionen benennen k\"onnen. Diese Art der
Variation des Namens ist nat\"urlich nicht sinnvoll. Sie tr\"agt keine
Information \"uber den Unterschied der beiden Funktionen. Auch sagt
der Name nahezu nichts \"uber den Zweck der Funktion aus.

Die Namensgebung f\"allt mitunter nicht leicht --- manchmal ist es
sogar der schwierigste Aspekt des Programmierens!  Ausdrucksstarke
Namen zu finden lohnt sich aber. Ausdrucksstark bedeutet, dass sich
aus dem Namen R\"uckschl\"usse auf den Zweck ziehen lassen sollte.

\begin{important}[Benennung von Funktionen und Skripten]
  Die Namen von Funktionen und Skripten sollten m\"oglichst viel \"uber
  die Funktionsweise oder den Zweck aussagen (\file{firingrates.m}
  statt \file{uebung.m}). Gute Namen f\"ur Funktionen und Skripte sind
  die beste Dokumentation.
\end{important}

In Namen verbietet \matlab{} verbietet Leerzeichen, Sonderzeichen und
Umlaute. Namen d\"urfen auch nicht mit Zahlen anfangen. Es mach f\"ur
die Namensgebung selbst keine weiteren Vorgaben. Allerdings folgt die
Benennung der in \matlab{} vordefinierten Funktionen gewissen Mustern:
\begin{itemize}
\item Namen werden immer klein geschrieben.
\item Es werden gerne Abk\"urzungen eingesetzt (z.B. \code{xcorr()}
  f\"ur die Kreuzkorrelation oder \code{repmat()} f\"ur ``repeat matrix'')
\item Funktionen, die zwischen Formaten konvertieren sind immer nach
  dem Muster ``format2format'' (z.B. \code{num2str()} f\"ur die
  Konvertierung ``number to string'', Umwandlung eines numerischen
  Wertes in einen Text) benannt.
\end{itemize}

Andere \"ubliche Muster sind der \emph{camelCase}, bei dem die
Anf\"ange zusammengesetzter Worte jeweils gro{\ss} geschrieben werden
oder auch die Verwendung von Unterstrichen zur Trennung von
Namenskomponenten. Eine Funktion, die die Anzahl von
Aktionspotentialen bestimmt k\"onnte etwa \file{spikeCount.m} oder
\file{spike\_count.m} benannt werden.


\section{Namensgebung von Variablen und Konstanten}

F\"ur die Bennennung von Variablen und Konstanten gelten die gleichen
Regeln wie f\"ur die Namen von Funktionen und Skripten. Die Maxime von
gutem Programmierstil ist: \emph{``Programmcode muss lesbar
  sein.''}. Dabei helfen gute Namen ungemein. Auch wenn es schwer
f\"allt passende und trotzdem nicht zu lange Namen zu finden, sollte
einer gute Namensgebung sehr ernst genommen werden.

W\"ahrend die Namen von Funktionen und Skripten ihren Zweck
beschreiben, sollten die Namen von Variablen ihren Inhalt
beschreiben. Eine Variable, die die mittlere Anzahl von
Aktionspotentialen speichert, k\"onnte also
\varcode{average\_spike\_count} hei{\ss}en. Wenn die Variable nicht
nur einen sondern mehrere Werte aufnimmt, dann ist der Plural
angebracht (\varcode{average\_spike\_counts}).

Die Laufvariablen von \code{for}-Schleifen werden oft nur \varcode{i},
\varcode{j} oder \varcode{k} benannt und sollten aber die einzige Ausnahme
bzgl. ausdrucksstarker Namensgebung bleiben.

\begin{important}[Benennung von Variablen]
  Die Namen von Variablen sollten m\"oglichst viel \"uber ihren Inhalt
  aussagen (\varcode{spike\_count} statt \varcode{x}). Gute Namen
  f\"ur Variablen sind die beste Dokumentation.
\end{important}


\section{Codestil}

Die Lesbarkeit von Programmen wird sehr durch den Codestil
beeinflusst. Ein Programm, in dem z.B. Schleifenk\"orper nicht (oder
zuf\"allig) einger\"uckt sind ist deutlich schwerer zu lesen und zu
verstehen, als eines, in dem eine konsistente Einr\"uckung vorgenommen
wurde. Mit der Tastenkombination \keycode{Ctrl-I} (\keycode{Strg-I}
auf der deutschen Tastatur) kann ein markierter Bereich im \matlab{}
Editor automatisch richtig einger\"uckt werden.

Sparsam und konsistent eingef\"ugte einzelne Leerzeilen sind
hervorragend geeignet, um logische Abschnitte eines Programm zu
trennen. Zu viele Leerzeilen haben den Nachteil, dass das Programm
nicht mehr auf eine Seite passt und dadurch leichter der \"Uberblick
verlorgen geht.

Die beiden folgenden Listings \ref{chaoticcode} und \ref{cleancode}
zeigen die Implementation des random-walk einmal eher chaotisch und
einmal aufger\"aumt und \"ubersichtlich.
 
\begin{lstlisting}[label=chaoticcode, caption={Un\"ubersichtliche Implementation des Random-walk.}]
num_runs = 10;
max_steps = 1000;

positions = zeros(max_steps, num_runs);

for run = 1:num_runs

    
for step = 2:max_steps

x = randn(1);
if x<0
positions(step, run)= positions(step-1, run)+1;
    
       
elseif x>0
 positions(step,run)=positions(step-1,run)-1;
 end
end
end
\end{lstlisting}

\pagebreak[4]

\begin{lstlisting}[label=cleancode, caption={\"Ubersichtliche Implementation des Random-walk.}]
num_runs = 10;
max_steps = 1000;
positions = zeros(max_steps, num_runs);

for run = 1:num_runs
    for step = 2:max_steps
        x = randn(1);
        if x < 0
            positions(step, run) = positions(step-1, run) + 1;
        elseif x > 0
            positions(step, run) = positions(step-1, run) - 1;
        end
    end
end
\end{lstlisting}

\section{Verwendung von Kommentaren}

Kommentarzeilen werden in \matlab{} mit dem Prozentzeichen \code{\%}
gekennzeichnet.  Gezielt und sparsam eingesetzte Kommentare sind f\"ur
das Verst\"andnis eines Programms sehr n\"utzlich.  Am wichtigsten
sind kurze Kommentare, die den Zweck und das Ziel eines Abschnitts im
Programm erl\"autern (z.B. \varcode{\% compute mean firing rate over all
  trials}).

Viele und h\"aufige Kommentare k\"onnen in der Entwicklungsphase eines
Programms sehr hilfreich sein, bl\"ahen aber den Code auf. Durch die
Verwendung guter Variablen- und Funktionsnamen sollten die meisten
Zeilen sowieso weitestgehend selbsterkl\"arend sein.

Die beste Dokumentation ist der Code selbst. Gut geschriebener Code
mit ausdrucksstarken Variablen- und Funktionsnamen ben\"otigt keine
Kommentare, um den Zweck einzelner Zeilen zu erkl\"aren. z.B. ist\\
\varcode{ x = x + 2;   \% add two to x}\\
ein v\"ollig unn\"otiger Kommentar.

\begin{important}[Verwendung von Kommentaren]
  \begin{itemize}
  \item Kommentare sollen die Absicht eines Programmabschnitts beschreiben.
  \item Kommentare sind gut und wichtig --- sie m\"ussen aber richtig
    sein!
  \item Ein falscher Kommentar ist schlimmer als gar kein Kommentar!
  \item Kommentare m\"ussen gepflegt werden, sonst sind sie wertlos!
  \end{itemize}
  \widequote{Good code is its own best documentation. As you're about to add
    a comment, ask yourself, ``How can I improve the code so that this
    comment isn't needed?'' Improve the code and then document it to
    make it even clearer.}{Steve McConnell}
\end{important}

\pagebreak[4]
\section{Dokumentation von Funktionen}

Bei allen vordefinierten \matlab{} Funktionen findet sich am Anfang
eine Kommentarblock, der den Zweck der Funktion, die verschiedenen
M\"oglichkeiten des Funktionsaufrufs und die Argumente und
R\"uckgabewerte beschreibt. Mit dem \code{help}- Befehl wird dieser
Kommentarblock angezeigt. Auch in eigenen Funktionen sind
diese Kommentare sehr wichtig. Siehe Listing~\ref{localfunctions}
f\"ur ein Beispiel einer gut dokumentierten Funktion.

\begin{important}[Dokumentation von Funktionen]
  Funktionen m\"ussen unbedingt kommentiert werde!
  \begin{itemize}
  \item In wenigen Zeilen kurz den Zweck der Funktion beschreiben.
  \item Den Funktionskopf nocheinmal hinschreiben, damit
    klar ist, in welcher Reihenfolge Argumente \"ubergeben werden.
  \item F\"ur jedes Funktionsargument die Bedeutung, der erwartete
    Datentyp (Zahl, Vektor, Matrix, etc.), und eventuell die Einheit,
    in der die Zahlen erwartet werden (z.B. Sekunden).
  \item Ebenso m\"ussen die R\"uckgabewerte beschrieben werden.
  \end{itemize}
\end{important}


\section{Auslagerung von Aufgaben in Funktionen}

Kommentare oder Leerzeilen werden benutzt, um logische Abschnitte des
Codes abzutrennen und kurz zu erkl\"aren. Wenn eine
solche inhaltliche Trennung einzuf\"ugt wird, sollte man sich immer fragen,
ob dieser Teil des Programms nicht in eine eigene Funktion ausgelagert
werden sollte. Fast immer kann dies bejaht werden.

Abschnitte nicht auszulagern f\"uhrt zu sehr langen
\codeterm{m-files}, die leicht un\"ubersichtlich werden. Diese Art von
Code wird \codeterm{Spaghetticode} genannt. Es ist h\"ochste Zeit
\"uber Auslagerung in Funktionen nachzudenken.

\begin{important}[Gliederung in Funktionen]
  Wann sollten Programmteile in eigene Funktionen ausgelagert werden?
  \begin{itemize}
  \item Wenn innerhalb einer Funktion oder eines Skripts mehr als zwei
    Einr\"uckungsebenen gebraucht werden.
  \item Wenn sich Strukturen im Code mehr als einmal wiederholten.
  \item Wenn man versucht ist, wiederholte Strukturen  mit Copy and Paste zu erzeugen.
  \end{itemize}
\end{important}

\subsection{Lokale Funktionen und geschachtelte Funktionen}

Das Auslagern von Funktionalit\"at in eigene Funktionen f\"uhrt dazu,
dass eine F\"ulle von Dateien erzeugt wird, die die
\"Ubersichtlichkeit nicht unbedingt erh\"oht. Wenn die auszulagernde
Funktionalit\"at an vielen Stellen ben\"otigt wird ist es dennoch sehr
sinnvoll dies zu tun. Wenn Funktionen nur von einzelnen anderen
Funktionen verwendet werden, dann bietet \matlab{} die M\"oglichkeit
sogenannte \codeterm[Funktion!lokale]{lokale Funktionen} oder auch
\codeterm[Funktion!geschachtelte]{geschachtelte Funktionen}
(\enterm{nested functions}) in einer einzelnen Datei zu
erstellen. Listing \ref{localfunctions} zeigt ein Beispiel f\"ur eine
lokale Funktion.

\pagebreak[3]
\lstinputlisting[label=localfunctions, caption={Beispiel f\"ur den
  Einsatz von lokalen Funktionen.}]{calculateSines.m}

Lokale Funktionen existieren in der gleichen Datei und sind nur dort
verf\"ugbar. Jede Funktion hat ihren eigenen G\"ultigkeitsbereich, das
hei{\ss}t, dass Variablen aus den aufrufenden Funktionen nicht
sichtbar sind. 

Bei sogenannten \codeterm[Funktion!geschachtelte]{geschachtelten
Funktionen} ist das anders. Diese werden innerhalb eines
Funktionsk\"orpers (zwischen den Schl\"usselworten \code{function} und
dem \code{end} definiert und k\"onnen auf alle Variablen der
``Mutterfunktion'' zugreifen und diese auch ver\"andern. Folglich
sollten sie nur mit Bedacht eingesetzt werden.


\section{Besonderheiten bei Skripten}

Ein \"ahnliches Problem wurde schon bei der Einf\"uhrung der Skripte
erw\"ahnt. Variablen, die in Skripten definiert werden sind global im
\codeterm{Workspace} verf\"ugbar. Es besteht die Gefahr von
Namenskollisionen. Problem dabei ist, dass der Nutzer gar nicht
mitbekommt, wenn eine Variable redefiniert oder neuen Inhalt
zugewiesen bekommt. Fehler, die auf derartigen Kollisionen beruhen
sind h\"aufig nur schwer zu finden, da das Programm f\"ur sich korrekt
aussieht.

Um dieses Problem zu vermeiden sollten Skripte genauso wie Funktionen
eine spezifische Aufgabe unabh\"angig vom Kontext erf\"ullen. Diese
Aufgabe ist dann nat\"urlich komplexer als die einer
Funktion. z.B. k\"onnte die Aufgabe eines Skriptes sein, die
Spiketrains aller aufgenommenen Zellen zu analysieren. Gute Skripte
sind trotzdem nicht \"uberm\"a{\ss}ig lang und deshalb leicht zu
verstehen.

Ein weiterer, sehr wichtiger Vorteil von zweckbestimmten Skripten ist,
dass sie immer als ganzes ausf\"uhrbar sind --- am einfachsten mit
\keycode{F5} aus dem \matlab-Editor heraus. Wenn ein Fehler auftritt
ist in der Fehlermeldung die Zeilennummer des fehlerhaften Codes
angegeben. Das ist eine sehr wichtige Information, um den Fehler
beheben zu k\"onnen.

\"Ubergeordnete Skripte k\"onnen dann einfach nacheinander
spezifischere Skripte aufrufen. Durch die Namen der aufgerufenen
Skripte ist dann klar, was passieren wird, und durch die
Unabh\"angigkeit der Skripte kommt es nicht zu Kollisionen.

\begin{important}[Struktur von Skripten]
  \begin{itemize}
  \item Skripte sollten genauso wie Funktionen spezifische Aufgaben
    l\"osen und nicht zu lang sein.

  \item Skripte sollten unabh\"angig von irgendwelchen Variablen im
    \codeterm{Workspace} f\"ur sich alleine geschlossen lauff\"ahig
    sein.
    
  \item Es empfiehlt sich zu Beginn eines Skriptes alle Variablen im
    \codeterm{Workspace} zu l\"oschen (\code{clear}). Meist ist auch
    ein \code{close all}, um alle Figures zu schlie{\ss}en,
    angebracht.

  \item Am Ende eines Skriptes sollte der \codeterm{Workspace}
    mithilfe von \code{clear} wieder von all den Variablen ges\"aubert
    werden, die nicht mehr ben\"otigt werden.
  \end{itemize}
\end{important}

\section{Fazit}

Programmcode soll lesbar sein. Namen von Variablen, Funktionen und
Skripten sollten ausdrucksstark sein und R\"uckschl\"usse auf den
Inhalt oder den Zweck erlauben. Einen pers\"onlichen Programmierstil
zu entwickeln ist v\"ollig in Ordnung solange er konsistent ist. In
machen Programmiersprachen gibt es Traditionen und \"Ubereink\"unfte,
diese sollten dann beachtet werden. 

Wiederholte Programmabschnitte sollten in Funktionen ausgelagert
werden. Wenn diese nicht von globalem Interesse sind, kann mit
\codeterm[Funktion!lokale]{lokalen} oder
\codeterm[Funktion!geschachtelte]{geschachtelten
  Funktionen} die \"Ubersichtlichkeit erh\"oht werden.

Es lohnt sich auf den eigenen Programmierstil zu
achten!\footnote{Buchtip: Robert C. Martin: \textit{Clean Code: A
    Handbook of Agile Software Craftmanship}, Prentice Hall}

\shortquote{Programs must be written for people to read, and only
  incidentally for machines to execute.}{Abelson / Sussman}

\shortquote{Any fool can write code that a computer can
  understand. Good programmers write code that humans can
  understand.}{Martin Fowler}

\shortquote{First, solve the problem. Then, write the code.}{John
  Johnson}


\selectlanguage{english}