diff --git a/header.tex b/header.tex index aeda8d4..98862a2 100644 --- a/header.tex +++ b/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}} diff --git a/programmingstyle/lecture/programmingstyle.tex b/programmingstyle/lecture/programmingstyle.tex index 0807c9d..4284b14 100644 --- a/programmingstyle/lecture/programmingstyle.tex +++ b/programmingstyle/lecture/programmingstyle.tex @@ -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}