scientificComputing/programmingstyle/lecture/programmingstyle.tex

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

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 Monaten,
leicht f\"allt den Programmablauf nachzuvollziehen und zu
verstehen. Guter Programmierstil zahlt sich auch f\"ur den Sch\"opfer
eines Programmes aus.

Guter Programmierstil greift auf unterschiedlichen Ebenen an:
\begin{enumerate}
\item Die Struktur von Programmen.
\item Die Namensgebung von Skripten und Funktionen.  
\item Die Namensgebung fuer Variablen und Konstanten.
\item Die Verwendung von Einr\"uckungen und Leerzeilen um Bl\"ocke im Code hervorzuheben.
\item Verwendung von Kommentaren und Hilfetexten.
\end{enumerate}

\section{Struktur von Programmen, Organisation von m-Files im Dateisystem}

In der Einf\"uhrung zu Funktionen und Skripten wurde schon einmal ein
typisches Programmlayout vorgestellt (Abbildung
\ref{programlayoutfig}). 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:
1. Wie werden Programme im Dateisystem organisiert? 2. 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 eingenen
``Documents'' (Linux) oder ``Eigene Dokumente'' (Windows) Ordner. Es
bietet sich an diesen als Wurzelverzeichnis f\"ur eigene Arbeiten zu
verwenden. Nat\"urlich kann auch jeder andere Ort gew\"ahlen
werden. In dem Beispiel in Abbildung \ref{fileorganizationfig} wird
innerhalb dieses Ordners f\"ur jedes Projekt ein eigener Unterordner
erstellt in welchem widerum f\"ur jedes Problem, jede Analyse ein
weitere Unterodner erstellt wird. In diesen liegen sowohl die
ben\"otigten m-files also auch die Resultate der Analyse (Abbildungen,
Dateien). Zu bemerken sind noch zwei weitere Dinge. Im Projektordner
existiert ein Skript (analysis.m), das dazu gedacht ist, alle Analysen
aufzurufen. Des Weiteren gitb es parallel zu den Projektordnern einen
``functions'' Ordner in dem Funktionen liegen, die in mehr als einem
Projekt oder einer Analyse gebraucht werden.

Wenn man sich dieses Layout anschaut 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
``load\_data.m'' Funktion in jeder Analyse vorkommt. In der Regel
wird dies nicht zu Konflikten f\"uhren, da \matlab{} zuforderst im
aktuellen Ordner nach passenden Dateien sucht (mehr Information in Box
\ref{matlabpathbox}).

\begin{figure}
  \includegraphics[width=0.75\textwidth]{program_organization}
  \titlecaption{\label{fileorganizationfig} M\"ogliche Oganisation 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}[t]{\label{matlabpathbox}Der \matlab{} Suchpfad}

  \begin{itemize}
  \item Suchpfad, was soll das.
  \item Reihenfolge.
  \item \"Andern des Pfades.
  \end{itemize}
  
  \includegraphics[width=0.75\textwidth]{search_path}
\end{ibox}

\section{Namensgebung von Funktionen und Skripten}

  \begin{enumerate}
    \item Die Namensgebung fuer Variablen und Konstanten.
    \item Die Namensgebung von Skripten und Funktionen.  
    \item Die Verwendung von Einr\"uckungen und Leerzeilen um Bl\"ocke im Code hervorzuheben.
    \item Verwendung von Kommentaren und Hilfetexten.
  \end{enumerate}


  In verschiedenen Sprachen verschiedene Konventionen. In MATLAB ...
  \begin{itemize}
  \item Funktionen, Skripte: Kleinbuchstaben, Abk\"urzungen. (z.B. \verb+xcorr+, \verb+repmat+)
  \item Konvertierungen immer mit format2format (z.B. \verb+num2str+)
  \item Variablen immer klein, h\"aufig Abk\"urzungen.
  \item Kommentare h\"aufig fuer interne Zwecke aber ausf\"uhrliche Dokumentation mit Hilftexten.
  \end{itemize}


\section{Namensgebung von Variablen und Konstanten}

  \textbf{``Programmcode muss lesbar sein.''}
  \begin{enumerate}
  \item Variablen werden klein geschrieben. Wenn n\"otig entweder im
    \textit{camelCase} oder mit Unterstrichen (z.B. \verb+spikeCount+
    oder \verb+spike_count+).
  \item Funktionen und Skripte mit ausdrucksstarken Namen (z.B. \verb+loadSpikeData+).
  \item Kommentare sparsam. Eventuell um Abschnitte zu trennen.
  \item Hilfetexte: Ein Problem; sie m\"ussen aktuell sein sonst sind
    sie sch\"adlicher als wenn sie gar nicht da w\"aren.
  \item Einr\"uckung ist Pflicht.
  \item Bl\"ocke im Code werden durch 1 Leerzeile getrennt.
  \end{enumerate}


  Ihr d\"urft all das missachten und einen eingenen Stil entwickeln. Aber:\\
  \vspace{2.5cm}
  \centering
  \huge{Bleibt konsitent!}
  \vspace{2.5cm}
  \normalsize
  
  Es gibt dazu ganze B\"ucher. z.B. Robert C. Martin: \textit{Clean
    Code: A Handbook of Agile Software Craftmanship}, Prentice Hall