teaching/scientificComputing
Archived
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[chapter 4] translate code style chapter

Browse Source
This commit is contained in:
Jan Grewe 2018-10-09 17:59:50 +02:00
parent 104717cfe7
commit 4270b65442
1 changed files with 307 additions and 331 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

634
programmingstyle/lecture/programmingstyle.tex
View File

@ -1,215 +1,208 @@
\chapter{\tr{Programming style}{Programmierstil}} \chapter{\tr{Code style}{Programmierstil}}
\shortquote{Any code of your own that you haven't looked at for six or \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 more months might as well have been written by someone
else.}{Eagleson's law} else.}{Eagleson's law}
\selectlanguage{ngerman} %\selectlanguage{ngerman}
Cultivating a good code style not a matter of good taste but is
a key ingredient for understandability, maintainability and in the end
facilitates reproducibility of scientific results. Programs should be
written and structured in a way that supports outsiders as well the
author himself --- a few weeks or months after it was written --- to
understand the programs' rationale. Clean code pays off for the
original author as well as others that are supposed to use the code.
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 Clean code addresses several issues:
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} \begin{enumerate}
\item Die Dateistruktur von Programmen. \item The programs' structure.
\item Die Namensgebung von Skripten und Funktionen. \item Naming of scripts and functions.
\item Die Namensgebung f\"ur Variablen und Konstanten. \item Naming of variables and constants.
\item Die Verwendung von Einr\"uckungen und Leerzeilen um Bl\"ocke im \item Application of indentation empty lines to define blocks.
Code hervorzuheben. \item Use of comments and inline documentation.
\item Verwendung von Kommentaren und Hilfetexten. \item Delegation of repeated code to functions and dedicated
\item Auslagerung von Funktionalit\"at in eigene Funktionen. subroutines.
\end{enumerate} \end{enumerate}
\section{Organisation von Programmdateien im Dateisystem} \section{Organization of programs on the file system}
In der Einf\"uhrung zu Funktionen und Skripten wurde schon einmal ein While introducing scripts and functions we suggested a typical program
typisches Programmlayout vorgestellt (box\,\ref{whenscriptsbox}). Hier layout (box\,\ref{whenscriptsbox}). The idea is to create a single
wurde vorgeschlagen ein Skript als Kontrollskript zu verwenden. Dieses entry point by having one script that controls the rest of program by
kontrolliert den weiteren Programmablauf, ruft Funktionen auf, managing data and results and calling functions that work on the data
\"ubergibt Argumente und nimmt R\"uckgabewerte entgegen. Eine solche and produce the results. Applying this structure makes it easy to
Struktur macht es einfach den Ablauf zu verstehen. Es bleibt aber die understand the flow of the program but two questions remain: (i) How
Frage, wie man das Kontrollskript unter den anderen \codeterm{m-files} to organize the files on the file system and (ii) how to name them
als solches erkennt. Um dieses zu erleichtern gilt es zwei Dinge zu that the controlling script is easily identified among the other
beachten: (i) Wie werden Programme im Dateisystem organisiert? (ii) Wie \codeterm{m-files}.
werden Programme benannt?
Upon installation ``MATLAB'' creates a folder called \emph{MATLAB} in
Es hilft ungemein, wenn zusammengeh\"orige Skripte und Funktionen im the user space (Windows: My files, Linux: Documents, MacOS:
gleichen Ordner auf der Festplatte zu finden sind. Es bietet sich also Documents). Since this folder is already appended to the Matlab search
an, f\"ur jede Analyse einen eigenen Ordner anzulegen und in diesem path (Box~\ref{matlabpathbox}), it is easiest to stick to it for the
die zugeh\"origen \codeterm{m-files} abzulegen. Auf eine tiefere moment. Of course, any other location can specified as well. Generally
Schachtelung in weitere Unterordner kann in der Regel verzichtet it is of great advantage to store related scripts and functions within
werden. \matlab{} erzeugt einen ``MATLAB'' Ordner im eigenen the same folder on the hard drive. An easy approach is to create a
\file{Documents} (Linux) oder \file{Eigene Dokumente} (Windows) project-specific folder structure that contains sub-folders for each
Ordner. Es bietet sich an, diesen Ordner als Wurzelverzeichnis f\"ur task (analysis) and to store all related \codeterm{m-files}
eigene Arbeiten zu verwenden. Nat\"urlich kann auch jeder andere Ort (screenshot \ref{fileorganizationfig}). In these task-related folders
gew\"ahlt werden. In dem Beispiel in \figref{fileorganizationfig} wird one may consider to create a further sub-folder to store results
innerhalb dieses Ordners f\"ur jedes Projekt ein eigener Unterordner (created figures, result data). On the project level a single script
erstellt, in welchem wiederum f\"ur jedes Problem, jede Analyse ein (analysis.m) controls the whole process. In parallel to the project
weiterer Unterodner erstellt wird. In diesen liegen sowohl die folder we suggest to create an additional folder for functions that
ben\"otigten \codeterm{m-files} also auch die Resultate der Analyse are or may be relevant across different projects.
(Abbildungen, Daten-Dateien). Zu bemerken sind noch zwei weitere
Dinge. Im Projektordner existiert ein Skript (analysis.m), das dazu Within such a structure it is quite likely that programs in different
gedacht ist, alle Analysen aufzurufen. Des Weiteren gibt es parallel projects share the same name (e.g. a ``load\_data.m''
zu den Projektordnern einen \file{functions}-Ordner in dem Funktionen function). Usually this will not lead to conflicts due to the way
liegen, die in mehr als einem Projekt oder einer Analyse gebraucht matlab searches for matching functions which always starts in the
werden. current folder (more information on the \matlab-path in
Box~\ref{matlabpathbox}).
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] \begin{figure}[tp]
\includegraphics[width=0.75\textwidth]{program_organization} \includegraphics[width=0.75\textwidth]{program_organization}
\titlecaption{\label{fileorganizationfig} M\"ogliche Organisation von \titlecaption{\label{fileorganizationfig} Possible folder structure
Programmcode im Dateisystem.}{ F\"ur jedes Projekt werden for maintaining program code on the file system.}{For each project
Unterordner f\"ur die einzelnen Analysen angelegt. Auf Ebene des one maintains an individual folder in which analyses or tasks may
Projektes k\"onnte es ein Skript (hier ``analysis.m'') geben, be structured in sub-folders. Within each analysis a ``main.m''
welches alle Analysen in den Unterordnern anst\"o{\ss}t.} script is the entry point for the analyses. On the project level
there could be a single script that triggers and controls all
analyses and tasks in the sub-folders. Functions that are of
general interest across projects are best kept in a dedicated
folder outside the project sub-structure.}
\end{figure} \end{figure}
\begin{ibox}[tp]{\label{matlabpathbox}Der \matlab{} Suchpfad} \begin{ibox}[tp]{\label{matlabpathbox}\matlab{} search path}
Der Suchpfad definiert, wo \matlab{} nach Skripten und Funktionen The \codeterm{search path} defines where \matlab{} looks for scripts
sucht. Wird eine Funktion aufgerufen wird zun\"achst im aktuellen and functions. When calling a function from the command line
Arbeitsverzeichnis einem Treffer gesucht. Schl\"agt diese Suche \matlab{} needs to figure out which function is addressed and starts
fehl, so arbeitet sich \matlab{} durch den \codeterm{Suchpfad} looking for it in the current path. If this fails it will crawl all
(siehe Abbildung). Der \codeterm{Suchpfad} ist eine Liste von locations listed in the search path (see figure). The
Ordnern in denen \matlab{} nach Funktionen und Skripten suchen \codeterm{search path} is basically a list of folders. \matlab{}
soll. Die Suche nach der aufgerufenen Funktion wird dabei von oben will go through this list from front to end and the search will stop
nach unten durchgef\"uhrt. Das heisst, dass es bei on the first match. This implies that the order in the search path
Namensgleichheit eine Rolle spielen kann an welcher Stelle im may affect which version of functions that share the same name is
Suchpfad der erste Treffer gefunden wird. Wichtig: \matlab{} sucht used. Note: \matlab{} does not perform a recursive search. That is,
nicht rekursiv! Wenn die gew\"unschte Funktion in einem Unterordner a function that resides in a sub-folder that is not explicitly
des aktuellen Arbeitsverzeichnisses liegt, dieses aber nicht listed in the \codeterm{search path} will not be found.
explizit im Suchpfad enthalten ist, so wird die Funktion nicht
gefunden.
\vspace{2ex} \vspace{2ex}
\includegraphics[width=0.9\textwidth]{search_path} \includegraphics[width=0.9\textwidth]{search_path}
\vspace{1.5ex} \vspace{1.5ex}
Der Suchpfad kann sowohl \"uber die Kommandozeile mit dem Kommandos The search path can be managed from the command line by using the
\code{addpath()} und \code{userpath()} als auch\"uber die in der functions \code{addpath()} or \code{userpath()}. Alternatively, the
Abbildung gezeigte GUI angezeigt und eingestellt werden. Die GUI \matlab{} UI offers a graphical tool for adding/removing paths, or
erlaubt Ordner aus dem Suchpfad zu entfernen, neue Ordner (optional changing the order of entries.
inklusive aller Unterordner) hinzuzuf\"ugen oder die Reihenfolge der
Pfade zu ver\"andern. The current working directory can be changed via the UI or also the
command line using the command \code{cd} (for change directory). The
Zum Wechseln des aktuellen Arbeitsverzeichnisses wird das Kommando current path is shown in the current directory text field of the UI
\code{cd} verwendet. \code{which} zeigt an, in welchem Pfad eine or can be requested using the command \code{pwd} (for present work
bestimmte Funktion gefunden wurde. Das aktuelle Areitsverzeichnis directory). The function \code{which()} shows the full path of the
wird durch den Aufruf \code{pwd} auf der Kommandozeile ausgegeben. actually used function. For example, finding out which \code{mean()}
function is used gives a result similar to:
\begin{lstlisting}[label=useofwhich, caption={Use of 'which'}]
>> which('mean')
/Applications/MATLAB2018b.app/toolbox/matlab/datafun/mean.m
\end{lstlisting}
\end{ibox} \end{ibox}
\section{Namensgebung von Funktionen und Skripten} \section{Naming scripts and functions}
\matlab{} will search the search path (Box \ref{matlabpathbox})
\matlab{} sucht Funktionen und Skripte ausschlie{\ss}lich anhand des exclusively by name. It is case-sensitive this implies that the files
Namens. Dabei spielt die Gro{\ss}- und Kleinschreibung eine Rolle. Die \file{test\_function.m} and \file{Test\_function.m} are two different
beiden Dateien \file{test\_funktion.m} und \file{Test\_Funktion.m} things. It is self-evident that choosing such names is nonsensical
zwei unterschiedliche Funktionen benennen k\"onnen. Diese Art der because the name contains no cue about the difference between the two
Variation des Namens ist nat\"urlich nicht sinnvoll. Sie tr\"agt keine and it further tells close to nothing about the purpose. Finding good
Information \"uber den Unterschied der beiden Funktionen. Auch sagt names is not trivial sometimes it is harder than the programming
der Name nahezu nichts \"uber den Zweck der Funktion aus. itself. Expressive names, however, pay off! Expressive means that the
name provides information about the purpose.
Die Namensgebung f\"allt mitunter nicht leicht --- manchmal ist es
sogar der schwierigste Aspekt des Programmierens! Ausdrucksstarke \begin{important}[Naming scripts and functions]
Namen zu finden lohnt sich aber. Ausdrucksstark bedeutet, dass sich Function and script names should be expressive in the sense that the
aus dem Namen R\"uckschl\"usse auf den Zweck ziehen lassen sollte. name provides information about the function's purpose
(\file{estimate\_firingrate.m} tells much more than
\begin{important}[Benennung von Funktionen und Skripten] \file{exercise1.m}). Choosing a good name replaces large parts of
Die Namen von Funktionen und Skripten sollten m\"oglichst viel \"uber the documentation.
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} \end{important}
In Namen verbietet \matlab{} verbietet Leerzeichen, Sonderzeichen und \matlab{} has a few rules about names: Names must not start with a
Umlaute. Namen d\"urfen auch nicht mit Zahlen anfangen. Es mach f\"ur number, they must not contain blanks or other special characters like
die Namensgebung selbst keine weiteren Vorgaben. Allerdings folgt die e.g. German Umlauts. Otherwise one is free to use whatever suits. The
Benennung der in \matlab{} vordefinierten Funktionen gewissen Mustern: names of pre-defined functions shipped with \matlab{} follows several
patterns:
\begin{itemize} \begin{itemize}
\item Namen werden immer klein geschrieben. \item Names are always lowercase.
\item Es werden gerne Abk\"urzungen eingesetzt (z.B. \code{xcorr()} \item Names are often abbreviations (e.g. \code{xcorr()}
f\"ur die Kreuzkorrelation oder \code{repmat()} f\"ur ``repeat matrix'') stands for cross-correlation \code{repmat()} for ``repeat matrix'').
\item Funktionen, die zwischen Formaten konvertieren sind immer nach \item Functions that convert between formats are named according to
dem Muster ``format2format'' (z.B. \code{num2str()} f\"ur die the pattern ``format2format'' (e.g. \code{num2str()} for ``number to string'' conversion).
Konvertierung ``number to string'', Umwandlung eines numerischen
Wertes in einen Text) benannt.
\end{itemize} \end{itemize}
Andere \"ubliche Muster sind der \emph{camelCase}, bei dem die There are other common patterns such as the \emph{camelCase} in which
Anf\"ange zusammengesetzter Worte jeweils gro{\ss} geschrieben werden the first character of compound words is capitalized. Other
oder auch die Verwendung von Unterstrichen zur Trennung von conventions use the underscore to separate the individual words
Namenskomponenten. Eine Funktion, die die Anzahl von \emph{snake\_case}. A function that counts the number of action
Aktionspotentialen bestimmt k\"onnte etwa \file{spikeCount.m} oder potentials could be named \file{spikeCount.m} or
\file{spike\_count.m} benannt werden. \file{spike\_count.m}.
\section{Namensgebung von Variablen und Konstanten} \section{Naming variables and constants}
F\"ur die Bennennung von Variablen und Konstanten gelten die gleichen \matlab{} applies the same rules for naming variables and constants as
Regeln wie f\"ur die Namen von Funktionen und Skripten. Die Maxime von for the naming of scripts and functions. The dictum of good
gutem Programmierstil ist: \emph{``Programmcode muss lesbar code style is: ``Program code must be readable.'' Expressive
sein.''}. Dabei helfen gute Namen ungemein. Auch wenn es schwer names are extraordinarily important in this respect. Even if it is
f\"allt passende und trotzdem nicht zu lange Namen zu finden, sollte tricky to find expressive names that are not overly long, naming
einer gute Namensgebung sehr ernst genommen werden. should be taken seriously.
W\"ahrend die Namen von Funktionen und Skripten ihren Zweck While the names of scripts and functions describe the purpose, names
beschreiben, sollten die Namen von Variablen ihren Inhalt of variables describe the stored content. A variable storing the
beschreiben. Eine Variable, die die mittlere Anzahl von average number of actions potentials could be called
Aktionspotentialen speichert, k\"onnte also \varcode{average\_spike\_count}. If this variable is meant to store
\varcode{average\_spike\_count} hei{\ss}en. Wenn die Variable nicht multiple spike counts the plural form would be appropriate
nur einen sondern mehrere Werte aufnimmt, dann ist der Plural (\varcode{average\_spike\_counts}).
angebracht (\varcode{average\_spike\_counts}).
The control variables used in the head of a \code{for} loop are often
Die Laufvariablen von \code{for}-Schleifen werden oft nur \varcode{i}, simply named \varcode{i}, \varcode{j} or \varcode{k}. This kind-of
\varcode{j} oder \varcode{k} benannt und sollten aber die einzige Ausnahme clashes with the previously made statements but since it is a very
bzgl. ausdrucksstarker Namensgebung bleiben. common pattern the meaning of such variables in the context of the
loop is quite obvious. This should, however, be the only exception to
\begin{important}[Benennung von Variablen] the general rule of expressive naming.
Die Namen von Variablen sollten m\"oglichst viel \"uber ihren Inhalt
aussagen (\varcode{spike\_count} statt \varcode{x}). Gute Namen \begin{important}[Naming of variables]
f\"ur Variablen sind die beste Dokumentation. The names of variables should be expressive. That is, the name
itself should tell about the content of the variable. The name
\varcode{spike\_count} tells much more about the stored information
than \varcode{x}. Choosing a good variable name replaces additional
comments.
\end{important} \end{important}
\section{Codestil} \section{Code style}
Readability of program code depends strongly on whether or not a
consistent code style is applied. A program that is only randomly
indented or that contains lots of empty lines is very hard to read and
to comprehend. Even though the \matlab{} language (as many others)
does not enforce indentation, indentation is very powerful for
defining coherent blocks. The \matlab{} editor supports this by an
auto-indentation mechanism. A selected section of the code and be
automatically indented by pressing the \keycode{Ctrl-I} combination.
Die Lesbarkeit von Programmen wird sehr durch den Codestil Interspersing empty lines is very helpful to separate regions in the
beeinflusst. Ein Programm, in dem z.B. Schleifenk\"orper nicht (oder code that belong together. Too many empty lines, however lead to
zuf\"allig) einger\"uckt sind ist deutlich schwerer zu lesen und zu hard-to-read code because it might require more space than a granted
verstehen, als eines, in dem eine konsistente Einr\"uckung vorgenommen by the screen and thus takes overview.
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 The following two listings show basically the same implementation of a
hervorragend geeignet, um logische Abschnitte eines Programm zu random walk once in a rather chaotic version (listing
trennen. Zu viele Leerzeilen haben den Nachteil, dass das Programm \ref{chaoticcode}) then in cleaner way (listing \ref{cleancode})
nicht mehr auf eine Seite passt und dadurch leichter der \"Uberblick
verlorgen geht.
Die beiden folgenden Listings \ref{chaoticcode} und \ref{cleancode} \begin{lstlisting}[label=chaoticcode, caption={Chaotic implementation of the random-walk.}]
zeigen die Implementation des random-walk einmal eher chaotisch und num_runs = 10; max_steps = 1000;
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); positions = zeros(max_steps, num_runs);
@ -232,7 +225,7 @@ end
\pagebreak[4] \pagebreak[4]
\begin{lstlisting}[label=cleancode, caption={\"Ubersichtliche Implementation des Random-walk.}] \begin{lstlisting}[label=cleancode, caption={Clean implementation of the random-walk.}]
num_runs = 10; num_runs = 10;
max_steps = 1000; max_steps = 1000;
positions = zeros(max_steps, num_runs); positions = zeros(max_steps, num_runs);
@ -249,33 +242,30 @@ for run = 1:num_runs
end end
\end{lstlisting} \end{lstlisting}
\section{Verwendung von Kommentaren} \section{Using comments}
Kommentarzeilen werden in \matlab{} mit dem Prozentzeichen \code{\%} It is common to provide extra information about the meaning of program
gekennzeichnet. Gezielt und sparsam eingesetzte Kommentare sind f\"ur code by adding comments to it. In \matlab{} comments are indicated by
das Verst\"andnis eines Programms sehr n\"utzlich. Am wichtigsten the percent character \code{\%}. Anything that is written in the
sind kurze Kommentare, die den Zweck und das Ziel eines Abschnitts im respective line following the percent is ignored and considered a
Programm erl\"autern (z.B. \varcode{\% compute mean firing rate over all comment. When used sparsely comments can immensely important for
trials}). understanding. Comments are short sentences that describe the meaning
of the (following) lines in the program code. During the initial
Viele und h\"aufige Kommentare k\"onnen in der Entwicklungsphase eines implementation of a function they can be used to guide the development
Programms sehr hilfreich sein, bl\"ahen aber den Code auf. Durch die but have the tendency to blow up the code and decrease readability. By
Verwendung guter Variablen- und Funktionsnamen sollten die meisten choosing expressive variable and function names, most lines should be
Zeilen sowieso weitestgehend selbsterkl\"arend sein. self-explanatory.
Die beste Dokumentation ist der Code selbst. Gut geschriebener Code For example stating the obvious does not really help:\\
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}\\ \varcode{ x = x + 2; \% add two to x}\\
ein v\"ollig unn\"otiger Kommentar.
\begin{important}[Verwendung von Kommentaren] \begin{important}[Using comments]
\begin{itemize} \begin{itemize}
\item Kommentare sollen die Absicht eines Programmabschnitts beschreiben. \item Comments describe the rationale of the respective code block.
\item Kommentare sind gut und wichtig --- sie m\"ussen aber richtig \item Comments are good and helpful --- they have to be true, however!
sein! \item A wrong comment is worse than a non-existent comment!
\item Ein falscher Kommentar ist schlimmer als gar kein Kommentar! \item Comments must be maintained just as the code. Otherwise they
\item Kommentare m\"ussen gepflegt werden, sonst sind sie wertlos! may become wrong and worse than meaningless!
\end{itemize} \end{itemize}
\widequote{Good code is its own best documentation. As you're about to add \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 a comment, ask yourself, ``How can I improve the code so that this
@ -284,153 +274,139 @@ ein v\"ollig unn\"otiger Kommentar.
\end{important} \end{important}
\pagebreak[4] \pagebreak[4]
\section{Dokumentation von Funktionen} \section{Documenting functions}
All pre-defined \matlab{} functions begin with a comment block that
Bei allen vordefinierten \matlab{} Funktionen findet sich am Anfang describes the purpose of the function, the required and optional
eine Kommentarblock, der den Zweck der Funktion, die verschiedenen arguments, and the values returned by the function. Using the
M\"oglichkeiten des Funktionsaufrufs und die Argumente und \code{help} command one can display these comments and learn how to
R\"uckgabewerte beschreibt. Mit dem \code{help}- Befehl wird dieser use the function properly. Self-written functions can and should be
Kommentarblock angezeigt. Auch in eigenen Funktionen sind documented in a similar way. Listing ~\ref{localfunctions} shows a
diese Kommentare sehr wichtig. Siehe Listing~\ref{localfunctions} well documented function.
f\"ur ein Beispiel einer gut dokumentierten Funktion.
\begin{important}[Documenting functions]
\begin{important}[Dokumentation von Funktionen] Functions must be properly documented, otherwise a user (the author
Funktionen m\"ussen unbedingt kommentiert werde! him- or herself) must read and understand the function code which is
a waste of time!
\begin{itemize} \begin{itemize}
\item In wenigen Zeilen kurz den Zweck der Funktion beschreiben. \item Describe with a few sentences the purpose of the function.
\item Den Funktionskopf nocheinmal hinschreiben, damit \item Note the function head to illustrate the order of the argments.
klar ist, in welcher Reihenfolge Argumente \"ubergeben werden. \item For each argument state the purpose, the expected data type
\item F\"ur jedes Funktionsargument die Bedeutung, der erwartete (number, vector, matrix, etc.) and, if applicable, the unit in
Datentyp (Zahl, Vektor, Matrix, etc.), und eventuell die Einheit, which a provided number must be given (e.g. seconds if a time is
in der die Zahlen erwartet werden (z.B. Sekunden). expected).
\item Ebenso m\"ussen die R\"uckgabewerte beschrieben werden. \item The same for all return values.
\end{itemize} \end{itemize}
\end{important} \end{important}
\section{Auslagerung von Aufgaben in Funktionen} \section{Delegating tasks in functions}
Comments and empty lines are used to organize code into logical blocks
and to briefly explain what they do. Whenever one feels tempted to do
this, one could also consider to delegate the respective task to a
function. In most cases this is preferable.
Kommentare oder Leerzeilen werden benutzt, um logische Abschnitte des Not delegating the tasks leads to very long \codeterm{m-files} which
Codes abzutrennen und kurz zu erkl\"aren. Wenn eine can be confusing. Sometimes such a code is called ``spaghetti
solche inhaltliche Trennung einzuf\"ugt wird, sollte man sich immer fragen, code''. It is high time to think about delegation of tasks to
ob dieser Teil des Programms nicht in eine eigene Funktion ausgelagert functions.
werden sollte. Fast immer kann dies bejaht werden.
Abschnitte nicht auszulagern f\"uhrt zu sehr langen \begin{important}[Delegating to functions]
\codeterm{m-files}, die leicht un\"ubersichtlich werden. Diese Art von When should one consider delegating tasks to specific functions?
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} \begin{itemize}
\item Wenn innerhalb einer Funktion oder eines Skripts mehr als zwei \item Whenever one needs more than two indentation levels to
Einr\"uckungsebenen gebraucht werden. organize to code.
\item Wenn sich Strukturen im Code mehr als einmal wiederholten. \item Whenever the same lines of code are repeated more than once.
\item Wenn man versucht ist, wiederholte Strukturen mit Copy and Paste zu erzeugen. \item Whenever one is tempted to use copy-and-paste.
\end{itemize} \end{itemize}
\end{important} \end{important}
\subsection{Lokale Funktionen und geschachtelte Funktionen} \subsection{Local and nested functions}
Generally, functions live in their own \codeterm{m-files} that have
Das Auslagern von Funktionalit\"at in eigene Funktionen f\"uhrt dazu, the same name as the function itself. Delegating tasks to functions
dass eine F\"ulle von Dateien erzeugt wird, die die thus leads to a large set of \codeterm{m-files} which increases
\"Ubersichtlichkeit nicht unbedingt erh\"oht. Wenn die auszulagernde complexity and may lead to confusion. If the delegated functionality
Funktionalit\"at an vielen Stellen ben\"otigt wird ist es dennoch sehr is used in multiple instances, it is advisable to do so. On the other
sinnvoll dies zu tun. Wenn Funktionen nur von einzelnen anderen hand, when the delegated functionality is only used within the context
Funktionen verwendet werden, dann bietet \matlab{} die M\"oglichkeit of another function \matlab{} allows to define
sogenannte \codeterm[Funktion!lokale]{lokale Funktionen} oder auch \codeterm[function!local]{local functions} and
\codeterm[Funktion!geschachtelte]{geschachtelte Funktionen} \codeterm[function!nested]{nested functions} within the same
(\enterm{nested functions}) in einer einzelnen Datei zu file. Listing \ref{localfunctions} shows an example of a local
erstellen. Listing \ref{localfunctions} zeigt ein Beispiel f\"ur eine function definition.
lokale Funktion.
\pagebreak[3] \lstinputlisting[label=localfunctions, caption={Example
\pagebreak[3] for local functions.}]{calculateSines.m}
\lstinputlisting[label=localfunctions, caption={Beispiel f\"ur den
Einsatz von lokalen Funktionen.}]{calculateSines.m} Local function live in the same \codeterm{m-file} as the main function
and are only available in this context. Each local function has its
Lokale Funktionen existieren in der gleichen Datei und sind nur dort own \codeterm{scope}, that is, the local function can not access (read
verf\"ugbar. Jede Funktion hat ihren eigenen G\"ultigkeitsbereich, das or write) variables of the calling function.
hei{\ss}t, dass Variablen aus den aufrufenden Funktionen nicht
sichtbar sind. This is different in so called \codeterm[function!nested]{nested
functions}. These are defined within the body of the parent function
Bei sogenannten \codeterm[Funktion!geschachtelte]{geschachtelten (between the keywords \code{function} and \code{end}) and have full
Funktionen} ist das anders. Diese werden innerhalb eines access to all variables defined in the parent function. Working (in
Funktionsk\"orpers (zwischen den Schl\"usselworten \code{function} und particular changing) the parent's variables is handy on the one side,
dem \code{end} definiert und k\"onnen auf alle Variablen der but is also risky. One should take care when defining nested functions.
``Mutterfunktion'' zugreifen und diese auch ver\"andern. Folglich
sollten sie nur mit Bedacht eingesetzt werden.
\section{Specifics when using scripts}
A similar problem as with nested function arises when using scripts
\section{Besonderheiten bei Skripten} (instead of functions). All variables that are defined within a script
become available in the global \codeterm{Workspace}. There is the risk
Ein \"ahnliches Problem wurde schon bei der Einf\"uhrung der Skripte of name conflicts, that is, a called sub-script redefines or uses the
erw\"ahnt. Variablen, die in Skripten definiert werden sind global im same variable name and may \emph{silently} change its content. The
\codeterm{Workspace} verf\"ugbar. Es besteht die Gefahr von user will not be notified by this change and the calling script may
Namenskollisionen. Problem dabei ist, dass der Nutzer gar nicht expect a completely different content. Bugs that are based on such
mitbekommt, wenn eine Variable redefiniert oder neuen Inhalt mistakes are hard to find since the program itself looks perfectly
zugewiesen bekommt. Fehler, die auf derartigen Kollisionen beruhen fine.
sind h\"aufig nur schwer zu finden, da das Programm f\"ur sich korrekt
aussieht. To avoid such issues one should design scripts in a way that they
perform their tasks independent from other scripts and functions.
Um dieses Problem zu vermeiden sollten Skripte genauso wie Funktionen
eine spezifische Aufgabe unabh\"angig vom Kontext erf\"ullen. Diese A common use case for a script could be to control the analyses made
Aufgabe ist dann nat\"urlich komplexer als die einer on many datasets and to collect the results. A good script is still
Funktion. z.B. k\"onnte die Aufgabe eines Skriptes sein, die not too long and is thus easy to comprehend. Another advantage of
Spiketrains aller aufgenommenen Zellen zu analysieren. Gute Skripte small task-related scripts is that they can be directly executed by
sind trotzdem nicht \"uberm\"a{\ss}ig lang und deshalb leicht zu either calling them from the command line or pressing \keycode{F5} in
verstehen. the editor. Should it fail there will be a proper error message that
provides important information to track and fix the bug.
Ein weiterer, sehr wichtiger Vorteil von zweckbestimmten Skripten ist,
dass sie immer als ganzes ausf\"uhrbar sind --- am einfachsten mit \begin{important}[Structuring scripts]
\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} \begin{itemize}
\item Skripte sollten genauso wie Funktionen spezifische Aufgaben \item Similar to functions script should solve one task and should
l\"osen und nicht zu lang sein. not be too long.
\item Skripte sollten unabh\"angig von irgendwelchen Variablen im \item Scripts should work independently of existing variables in the
\codeterm{Workspace} f\"ur sich alleine geschlossen lauff\"ahig global workspace.
sein.
\item Es empfiehlt sich zu Beginn eines Skriptes alle Variablen im \item It is advisable to start a script with deleting variables
\codeterm{Workspace} zu l\"oschen (\code{clear}). Meist ist auch (\code{clear}) from the workspace and most of the times it is also
ein \code{close all}, um alle Figures zu schlie{\ss}en, good to close all open figures (\code{close all}).
angebracht.
\item Am Ende eines Skriptes sollte der \codeterm{Workspace} \item Clean up the workspace at the end of a script. Delete
mithilfe von \code{clear} wieder von all den Variablen ges\"aubert (\code{clear}) all variables that are no longer needed.
werden, die nicht mehr ben\"otigt werden.
\end{itemize} \end{itemize}
\end{important} \end{important}
\section{Fazit}
Programmcode soll lesbar sein. Namen von Variablen, Funktionen und \section{Summary}
Skripten sollten ausdrucksstark sein und R\"uckschl\"usse auf den
Inhalt oder den Zweck erlauben. Einen pers\"onlichen Programmierstil Program code must be readable. Names of variables, functions and
zu entwickeln ist v\"ollig in Ordnung solange er konsistent ist. In scripts should be expressive and describe their purpose (scripts and
machen Programmiersprachen gibt es Traditionen und \"Ubereink\"unfte, functions) or their content (variables). Cultivating a personalized
diese sollten dann beachtet werden. code style is perfectly fine as long as it is consistent. Many
programming languages or communities have their own traditions. It is
advisable to adhere to these.
Wiederholte Programmabschnitte sollten in Funktionen ausgelagert Repeated tasks should (to be read as must) be delegated to
werden. Wenn diese nicht von globalem Interesse sind, kann mit functions. In cases in which a function is only locally applied and
\codeterm[Funktion!lokale]{lokalen} oder not of more global interest across projects consider to define it as
\codeterm[Funktion!geschachtelte]{geschachtelten \codeterm[function!local]{local function} or
Funktionen} die \"Ubersichtlichkeit erh\"oht werden. \codeterm[function!nested]{nested function}. Taking care to increase
readability and comprehensibility pays off, even to the author!
Es lohnt sich auf den eigenen Programmierstil zu \footnote{Reading tip: Robert C. Martin: \textit{Clean Code: A Handbook of
achten!\footnote{Buchtip: Robert C. Martin: \textit{Clean Code: A Agile Software Craftmanship}, Prentice Hall}
Handbook of Agile Software Craftmanship}, Prentice Hall}
\shortquote{Programs must be written for people to read, and only \shortquote{Programs must be written for people to read, and only
incidentally for machines to execute.}{Abelson / Sussman} incidentally for machines to execute.}{Abelson / Sussman}