diff --git a/programmingstyle/lecture/programmingstyle.tex b/programmingstyle/lecture/programmingstyle.tex index 8e634ab..5090943 100644 --- a/programmingstyle/lecture/programmingstyle.tex +++ b/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 -wird dies nicht zu Konflikten f\"uhren, da \matlab{} zuforderst im +``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}). @@ -105,45 +105,124 @@ aktuellen Ordner nach passenden Dateien sucht (mehr Information in Box \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} +\matlab{} sucht Funktionen und Skripte ausschlie{\ss}lich anhand der +Namen. Dabei spielt die Gro{\ss}- und Kleinschreibung eine Rolle. Das +hei{\ss}t, dass die Namen ``test_funktion.m'' und ``Test_funktion.m'' +zwei unterschiedliche Funktionen benennen k\"onnen. Diese Art +Variation des Namens ist nat\"urlich nicht sinnvoll. Sie tr\"agt keine +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 +angeht. Allerdings folgt die Benennung der vordefinierten Funktionen +gewissen Mustern: +\begin{itemize} +\item Namen werden immer klein geschrieben. +\item Es werden gerne Abk\"urzungen eingesetzt (z.B. \code{xcorr} + f\"ur die Kreuzkorrelation oder \code{repmat} f\"ur ``repeat matrix'') +\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. - In verschiedenen Sprachen verschiedene Konventionen. In MATLAB ... +\section{Namensgebung von Variablen und Konstanten} + +F\"ur die Bennennung von Variablen und Konstanten gelten die gleichen +Regeln wie f\"ur die Namen von Funktionen und Skripten. Die Maxime von +gutem Programmierstil ist: \emph{``Programmcode muss lesbar + sein.''}. Dabei helfen gute Namen ungemein. Auch wenn es schwer +f\"allt passende Namen zu finden, die nicht zu lang werden sollte man +sich auch da M\"uhe geben. + +Bei den Funktionen und Skripten fragt man danach, welchen Zweck sie +erf\"ullen, bei Variablen fragt man nach dem Inhalt. Eine Varaible die +die mittlere Anzahl Aktionspotentiale speichert k\"onnte also +\codeterm{average\_spike\_count} hei{\ss}en. Wenn die Variable nicht nur +einen sondern mehrere Werte aufnimmt, dann ist der Plural angebracht +(\codeterm{average\_spike\_counts}). + + +\section{Codestil} + +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 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. + \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} -\section{Namensgebung von Variablen und Konstanten} +Spaghetticode - \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 +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