more work, unfinished

programmingstyle/lecture/programmingstyle.tex

@@ -57,8 +57,8 @@ 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
+``load\_data.m'' Funktion in jeder Analyse vorkommt. In der Regel wird
-wird dies nicht zu Konflikten f\"uhren, da \matlab{} zuforderst im
+dies nicht zu Konflikten f\"uhren, da \matlab{} zuforderst im
 aktuellen Ordner nach passenden Dateien sucht (mehr Information in Box
 \ref{matlabpathbox}).
 
@@ -105,45 +105,124 @@ aktuellen Ordner nach passenden Dateien sucht (mehr Information in Box
 
 \section{Namensgebung von Funktionen und Skripten}
 
-  \begin{enumerate}
+\matlab{} sucht Funktionen und Skripte ausschlie{\ss}lich anhand der
-    \item Die Namensgebung fuer Variablen und Konstanten.
+Namen. Dabei spielt die Gro{\ss}- und Kleinschreibung eine Rolle. Das
-    \item Die Namensgebung von Skripten und Funktionen.  
+hei{\ss}t, dass die Namen ``test_funktion.m'' und ``Test_funktion.m''
-    \item Die Verwendung von Einr\"uckungen und Leerzeilen um Bl\"ocke im Code hervorzuheben.
+zwei unterschiedliche Funktionen benennen k\"onnen. Diese Art
-    \item Verwendung von Kommentaren und Hilfetexten.
+Variation des Namens ist nat\"urlich nicht sinnvoll. Sie tr\"agt keine
-  \end{enumerate}
+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, es lohnt sich aber
+ausdruckstarke Namen zu finden. Ausdrucksstark bedeutet, dass sich aus
+dem Namen ein R\"uckschluss auf den Zweck ziehen lassen sollte.
 
-
+\matlab{} macht keine weiteren Vorgaben, was die Namen
-  In verschiedenen Sprachen verschiedene Konventionen. In MATLAB ...
+angeht. Allerdings folgt die Benennung der vordefinierten Funktionen
+gewissen Mustern:
 \begin{itemize}
-  \item Funktionen, Skripte: Kleinbuchstaben, Abk\"urzungen. (z.B. \verb+xcorr+, \verb+repmat+)
+\item Namen werden immer klein geschrieben.
-  \item Konvertierungen immer mit format2format (z.B. \verb+num2str+)
+\item Es werden gerne Abk\"urzungen eingesetzt (z.B. \code{xcorr}
-  \item Variablen immer klein, h\"aufig Abk\"urzungen.
+  f\"ur die Kreuzkorrelation oder \code{repmat} f\"ur ``repeat matrix'')
-  \item Kommentare h\"aufig fuer interne Zwecke aber ausf\"uhrliche Dokumentation mit Hilftexten.
+\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 Aktionspotentiale
+berechnet k\"onnte etwa \codeterm{spikeCount.m} oder auch
+\codeterm{spike\_count.m} benannt werden. Leerzeichen, Sonderzeichen
+oder Anf\"ange mit Zahlen sind in Namen nicht erlaubt.
+
 
 \section{Namensgebung von Variablen und Konstanten}
 
-  \textbf{``Programmcode muss lesbar sein.''}
+F\"ur die Bennennung von Variablen und Konstanten gelten die gleichen
-  \begin{enumerate}
+Regeln wie f\"ur die Namen von Funktionen und Skripten. Die Maxime von
-  \item Variablen werden klein geschrieben. Wenn n\"otig entweder im
+gutem Programmierstil ist: \emph{``Programmcode muss lesbar
-    \textit{camelCase} oder mit Unterstrichen (z.B. \verb+spikeCount+
+  sein.''}. Dabei helfen gute Namen ungemein. Auch wenn es schwer
-    oder \verb+spike_count+).
+f\"allt passende Namen zu finden, die nicht zu lang werden sollte man
-  \item Funktionen und Skripte mit ausdrucksstarken Namen (z.B. \verb+loadSpikeData+).
+sich auch da M\"uhe geben.
-  \item Kommentare sparsam. Eventuell um Abschnitte zu trennen.
+
-  \item Hilfetexte: Ein Problem; sie m\"ussen aktuell sein sonst sind
+Bei den Funktionen und Skripten fragt man danach, welchen Zweck sie
-    sie sch\"adlicher als wenn sie gar nicht da w\"aren.
+erf\"ullen, bei Variablen fragt man nach dem Inhalt. Eine Varaible die
-  \item Einr\"uckung ist Pflicht.
+die mittlere Anzahl Aktionspotentiale speichert k\"onnte also
-  \item Bl\"ocke im Code werden durch 1 Leerzeile getrennt.
+\codeterm{average\_spike\_count} hei{\ss}en. Wenn die Variable nicht nur
-  \end{enumerate}
+einen sondern mehrere Werte aufnimmt, dann ist der Plural angebracht
+(\codeterm{average\_spike\_counts}).
 
 
-  Ihr d\"urft all das missachten und einen eingenen Stil entwickeln. Aber:\\
+\section{Codestil}
-  \vspace{2.5cm}
-  \centering
-  \huge{Bleibt konsitent!}
-  \vspace{2.5cm}
-  \normalsize
 
-  Es gibt dazu ganze B\"ucher. z.B. Robert C. Martin: \textit{Clean
+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.
+
+Gerne werden Leerzeielen eingef\"ugt um Abschnitte im Programm zu
+trennen. Das ist v\"ollig ok, wenn es konsistent und sparsam benutzt
+wird. Hier sollte eine Leerzeile ausreichen. Zu gro{\ss}e Abst\"ande
+f\"uhren dazu das das Programm nicht mehr auf eine Seite passt und man
+leicht den \"Uberblick verliert.
+
+
+ \TODO chaotisches und aufger\"aumtes Listing
+
+\section{Verwendung von Kommentaren}
+
+Kommentare k\"onnen ebenfalls sehr zum Verst\"andnis beitragen. 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. Auch in eingenen Funktionen, vor allem
+wenn auch andere Personen sie benutzen sollen, sind diese Kommentare
+hilfreich. H\"aufig werden kurze Kommentare eingesetzt um Abschnitte
+im Programm zu trennen. Hierbei sollte man auch sparsam sein. Jede
+Zeile zu erkl\"aren kann in der Entwicklungsphase eines Programms sehr
+hilfreich sein, bl\"aht aber den Code auf und bei der Verwendung guter
+Variablennamen sind viel Zeilen weitestgehend selbsterkl\"arend.
+
+\begin{important}
+  \begin{itemize}
+  \item Kommentare sind gut und wichtig aber: Sie m\"ussen richtig
+    sein!
+  \item Ein Kommentar der l\"ugt, ist schlimmer als gar kein Kommentar!
+  \item Kommentare m\"ussen gepflegt werden sonst sind sie mehr als
+    wertlos!
+  \end{itemize}
+\end{important}
+  
+
+\section{Auslagerung von Aufgaben in Funktionen}
+
+Spaghetticode
+
+inline functions
+
+
+\section{Besonderheiten bei Skripten}
+
+Achtung, globaler G\"ultigkeitsbereich!
+
+Kollision von Variablennamen.
+
+Best practice.
+
+\begin{important}
+  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.
+
+  Es lohnt sich!
+\end{important}
+
+
+Literatur zum Programmierstil: z.B. Robert C. Martin: \textit{Clean
   Code: A Handbook of Agile Software Craftmanship}, Prentice Hall