Merge branch 'programmingstyle'
This commit is contained in:
commit
dd07ea4d28
32
header.tex
32
header.tex
@ -167,13 +167,18 @@
|
||||
\newcommand{\reZpN}{\mathds{R^+_0}}
|
||||
\newcommand{\koZ}{\mathds{C}}
|
||||
|
||||
%%%%% english, german and code terms: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
%%%%% english, german, code and file terms: %%%%%%%%%%%%%%%
|
||||
\newcommand{\enterm}[1]{``#1''}
|
||||
\newcommand{\determ}[1]{\textit{#1}}
|
||||
\newcommand{\codeterm}[1]{\textit{#1}}
|
||||
\newcommand{\keycode}[1]{\texttt{#1}}
|
||||
\newcommand{\file}[1]{\texttt{#1}}
|
||||
|
||||
%%%%% key-shortcuts %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
\usepackage{tikz}
|
||||
\usetikzlibrary{shapes}
|
||||
\tikzstyle{keybox} = [draw=blue!50!black,fill=white,thick,rectangle,rounded corners,inner sep=3pt,inner ysep=2pt]
|
||||
\newcommand{\keycode}[1]{\begin{tikzpicture}[baseline=(box.base)]\node[keybox](box){\texttt{#1}};\end{tikzpicture}}
|
||||
|
||||
%%%%% code/matlab commands: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
\usepackage{textcomp}
|
||||
\newcommand{\code}[1]{\setlength{\fboxsep}{0.5ex}\colorbox{blue!10}{\texttt{#1}}}
|
||||
@ -254,14 +259,29 @@
|
||||
%%%%% important environment: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
% usage:
|
||||
%
|
||||
% \begin{important}
|
||||
% Something you should really rememeber.
|
||||
% \begin[Apples are important]{important}
|
||||
% Something you should really remember.
|
||||
% \end{important}
|
||||
%
|
||||
% results in a nicely colored box with the text inside.
|
||||
\newenvironment{important}
|
||||
{\begin{mdframed}[linecolor=blue!40,linewidth=1ex,%
|
||||
% The optional title of the box "Apples are important"
|
||||
% also appears in the list of important things.
|
||||
\DeclareFloatingEnvironment[
|
||||
fileext=loi,
|
||||
listname={\tr{Important things}{Wichtige Sachen}},
|
||||
name={},
|
||||
placement=t
|
||||
]{importantf}
|
||||
\newenvironment{important}[1][]%
|
||||
{\captionsetup{singlelinecheck=off,labelformat={empty},font={large,sf,it,bf}}
|
||||
\ifthenelse{\equal{#1}{}}%
|
||||
{\begin{mdframed}[linecolor=blue!40,linewidth=1ex,%
|
||||
backgroundcolor=blue!10,font={\sffamily}]}%
|
||||
{\begin{mdframed}[linecolor=blue!40,linewidth=1ex,%
|
||||
backgroundcolor=blue!10,font={\sffamily},%
|
||||
frametitle={\captionof{importantf}{#1}},frametitleaboveskip=-1ex,%
|
||||
frametitlebackgroundcolor=blue!40]}%
|
||||
}%
|
||||
{\end{mdframed}}
|
||||
|
||||
|
||||
|
||||
@ -22,7 +22,7 @@ Guter Programmierstil greift auf unterschiedlichen Ebenen an:
|
||||
\item Auslagerung von Funktionalit\"at in eigene Funktionen.
|
||||
\end{enumerate}
|
||||
|
||||
\section{Organisation von m-Files im Dateisystem}
|
||||
\section{Organisation von Programmdateien im Dateisystem}
|
||||
|
||||
In der Einf\"uhrung zu Funktionen und Skripten wurde schon einmal ein
|
||||
typisches Programmlayout vorgestellt (\figref{programlayoutfig}). Hier
|
||||
@ -121,8 +121,8 @@ sogar der schwierigste Aspekt des Programmierens! Ausdrucksstarke
|
||||
Namen zu finden lohnt sich aber. Ausdrucksstark bedeutet, dass sich
|
||||
aus dem Namen ein R\"uckschluss auf den Zweck ziehen lassen sollte.
|
||||
|
||||
\begin{important}
|
||||
Die Namen von Funktionen und Skripte sollten m\"oglichst viel \"uber
|
||||
\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.
|
||||
@ -171,7 +171,7 @@ Die Laufvariablen von \code{for}-Schleifen werden oft nur \code{i},
|
||||
\code{j} oder \code{k} benannt und sollten aber die einzige Ausnahme
|
||||
bzgl. ausdrucksstarker Namensgebung bleiben.
|
||||
|
||||
\begin{important}
|
||||
\begin{important}[Benennung von Variablen]
|
||||
Die Namen von Variablen sollten m\"oglichst viel \"uber ihren Inhalt
|
||||
aussagen (\code{spike\_count} statt \code{x}). Gute Namen
|
||||
f\"ur Variablen sind die beste Dokumentation.
|
||||
@ -242,7 +242,7 @@ end
|
||||
|
||||
\section{Verwendung von Kommentaren}
|
||||
|
||||
Kommentarzeilen werden in \matlab{} mit dem Prozentzeichen \cide{\%}
|
||||
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
|
||||
@ -260,7 +260,7 @@ Kommentare, um den Zweck einzelner Zeilen zu erkl\"aren. z.B. ist\\
|
||||
\code{ x = x + 2; \% add two to x}\\
|
||||
ein v\"ollig unn\"otiger Kommentar.
|
||||
|
||||
\begin{important}
|
||||
\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
|
||||
@ -279,7 +279,7 @@ R\"uckgabewerte beschreibt. Auch in eingenen Funktionen sind diese
|
||||
Kommentare sehr hilfreich. Siehe Listing~\ref{localfunctions} f\"ur
|
||||
ein Beispiel einer gut Dokumentierten Funktion.
|
||||
|
||||
\begin{important}
|
||||
\begin{important}[Dokumentation von Funktionen]
|
||||
Funktionen m\"ussen unbedingt kommentiert werde!
|
||||
\begin{itemize}
|
||||
\item In wenigen Zeilen kurz den Zweck der Funktion beschreiben.
|
||||
@ -304,7 +304,7 @@ Abschnitte nicht auszulagern f\"uhrt zu sehr langen
|
||||
Code wird \codeterm{Spaghetticode} genannt. Es ist h\"ochste Zeit
|
||||
\"uber Auslagerung in Funktionen nachzudenken.
|
||||
|
||||
\begin{important}
|
||||
\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
|
||||
@ -350,14 +350,37 @@ zugewiesen bekommt. Fehler, die auf derartigen Kollisionen beruhen
|
||||
sind h\"aufig nur schwer zu finden, da das Programm f\"ur sich korrekt
|
||||
aussieht.
|
||||
|
||||
\begin{important}
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
\"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}
|
||||
|
||||
Reference in New Issue
Block a user