diff --git a/header.tex b/header.tex index 64bea94..7cab69f 100644 --- a/header.tex +++ b/header.tex @@ -239,7 +239,7 @@ % The cooler programming language. \usepackage[within=chapter]{newfloat} \DeclareFloatingEnvironment[ - fileextension=lob, + fileext=lob, listname={\tr{Info Boxes}{Infoboxen}}, name={Info Box}, placement=t @@ -259,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}} diff --git a/programmingstyle/lecture/programmingstyle.tex b/programmingstyle/lecture/programmingstyle.tex index 41fb261..4284b14 100644 --- a/programmingstyle/lecture/programmingstyle.tex +++ b/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}