From 723339e509cd76e2c4e3f45d53ad90dc64a020fd Mon Sep 17 00:00:00 2001 From: Jan Benda Date: Sun, 15 Nov 2015 12:37:29 +0100 Subject: [PATCH 1/2] nice oval box for keycode --- header.tex | 9 +++++++-- programmingstyle/lecture/programmingstyle.tex | 4 ++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/header.tex b/header.tex index b492b64..64bea94 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}}} diff --git a/programmingstyle/lecture/programmingstyle.tex b/programmingstyle/lecture/programmingstyle.tex index 0807c9d..41fb261 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 @@ -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 From 072268879b44f16202a97991254a3c651af0ff89 Mon Sep 17 00:00:00 2001 From: Jan Benda Date: Sun, 15 Nov 2015 20:46:58 +0100 Subject: [PATCH 2/2] Added optional title to important environment --- header.tex | 25 ++++++++-- programmingstyle/lecture/programmingstyle.tex | 49 ++++++++++++++----- 2 files changed, 56 insertions(+), 18 deletions(-) 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}