Added optional title to important environment

programmingstyle/lecture/programmingstyle.tex

@@ -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.
@@ -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}