new programmingstyle chapter

Makefile

@@ -1,6 +1,6 @@
 BASENAME=scientificcomputing-script
 
-SUBDIRS=programming plotting statistics bootstrap regression likelihood pointprocesses designpattern
+SUBDIRS=programming plotting programmingstyle statistics bootstrap regression likelihood pointprocesses designpattern
 SUBTEXS=$(foreach subd, $(SUBDIRS), $(subd)/lecture/$(subd).tex)
 
 pdf : chapters $(BASENAME).pdf

programmingstyle/lecture/Makefile

@@ -0,0 +1,31 @@
+BASENAME=programmingstyle
+
+#TEXFILES=programmingstyle.tex
+
+PYFILES=$(wildcard *.py)
+PYPDFFILES=$(PYFILES:.py=.pdf)
+
+all : pdf 
+
+# script:
+pdf : $(BASENAME)-chapter.pdf
+
+$(BASENAME)-chapter.pdf : $(BASENAME)-chapter.tex $(BASENAME).tex $(PYPDFFILES) ../../header.tex
+	pdflatex -interaction=scrollmode $< | tee /dev/stderr | fgrep -q "Rerun to get cross-references right" && pdflatex -interaction=scrollmode $< || true
+
+$(PYPDFFILES) : %.pdf : %.py
+	python $<
+
+clean :
+	rm -f *~ 
+	rm -f $(BASENAME).aux $(BASENAME).log
+	rm -f $(BASENAME)-chapter.aux $(BASENAME)-chapter.log $(BASENAME)-chapter.out
+	rm -f $(PYPDFFILES) $(GPTTEXFILES)
+
+cleanall : clean
+	rm -f $(BASENAME)-chapter.pdf
+
+watchpdf :
+	while true; do ! make -q pdf && make pdf; sleep 0.5; done
+
+

programmingstyle/lecture/beamercolorthemetuebingen.sty

@@ -0,0 +1,61 @@
+% Copyright 2007 by Till Tantau
+%
+% This file may be distributed and/or modified
+%
+% 1. under the LaTeX Project Public License and/or
+% 2. under the GNU Public License.
+%
+% See the file doc/licenses/LICENSE for more details.
+
+\usepackage{color} 
+\definecolor{karminrot}{RGB}{165,30,55}
+\definecolor{gold}{RGB}{180,160,105}
+\definecolor{anthrazit}{RGB}{50 ,65 ,75 }
+
+\mode<presentation>
+
+\setbeamercolor*{normal text}{fg=anthrazit,bg=white}
+\setbeamercolor*{alerted text}{fg=anthrazit}
+\setbeamercolor*{example text}{fg=anthrazit}
+\setbeamercolor*{structure}{fg=gold,bg=karminrot}
+
+\providecommand*{\beamer@bftext@only}{%
+  \relax
+  \ifmmode
+    \expandafter\beamer@bftext@warning
+  \else
+    \expandafter\bfseries
+  \fi
+}
+\providecommand*{\beamer@bftext@warning}{%
+  \ClassWarning{beamer}
+    {Cannot use bold for alerted text in math mode}%
+}
+
+\setbeamerfont{alerted text}{series=\beamer@bftext@only}
+
+\setbeamercolor{palette primary}{fg=karminrot,bg=white}
+\setbeamercolor{palette secondary}{fg=gold,bg=white}
+\setbeamercolor{palette tertiary}{fg=anthrazit,bg=white}
+\setbeamercolor{palette quaternary}{fg=black,bg=white}
+
+\setbeamercolor{sidebar}{bg=karminrot!100}
+
+\setbeamercolor{palette sidebar primary}{fg=karminrot}
+\setbeamercolor{palette sidebar secondary}{fg=karminrot}
+\setbeamercolor{palette sidebar tertiary}{fg=karminrot}
+\setbeamercolor{palette sidebar quaternary}{fg=karminrot}
+
+\setbeamercolor{item projected}{fg=black,bg=black!20}
+
+\setbeamercolor*{block body}{}
+\setbeamercolor*{block body alerted}{}
+\setbeamercolor*{block body example}{}
+\setbeamercolor*{block title}{parent=structure}
+\setbeamercolor*{block title alerted}{parent=alerted text}
+\setbeamercolor*{block title example}{parent=example text}
+
+\setbeamercolor*{titlelike}{parent=structure}
+
+\mode
+<all>

programmingstyle/lecture/programmingstyle-chapter.tex

@@ -0,0 +1,17 @@
+\documentclass[12pt]{report}
+
+\input{../../header}
+
+\lstset{inputpath=../code}
+
+\graphicspath{{figures/}}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\begin{document} 
+
+\include{programmingstyle}
+
+\end{document}
+

programmingstyle/lecture/programmingstyle.tex

@@ -0,0 +1,129 @@
+\chapter{\tr{Programming style}{Programmierstil}}
+
+Guter Programmierstil ist keine Frage des guten Geschmacks sondern des
+Verst\"andnisses von Programmcode und ein Baustein in dem Bestreben
+wissenschaftlichen Erkenntnisgewinn reproduzierbar zu
+machen. 
+
+Programme sollten so geschrieben und strukturiert sein, dass es sowohl
+einem Au{\ss}enstehenden als auch einem selbst, nach ein paar Monaten,
+leicht f\"allt den Programmablauf nachzuvollziehen und zu
+verstehen. Guter Programmierstil zahlt sich auch f\"ur den Sch\"opfer
+eines Programmes aus.
+
+Guter Programmierstil greift auf unterschiedlichen Ebenen an:
+\begin{enumerate}
+\item Die Struktur von Programmen.
+\item Die Namensgebung von Skripten und Funktionen.  
+\item Die Namensgebung fuer Variablen und Konstanten.
+\item Die Verwendung von Einr\"uckungen und Leerzeilen um Bl\"ocke im Code hervorzuheben.
+\item Verwendung von Kommentaren und Hilfetexten.
+\end{enumerate}
+
+\section{Struktur von Programmen, Organisation von m-Files im Dateisystem}
+
+In der Einf\"uhrung zu Funktionen und Skripten wurde schon einmal ein
+typisches Programmlayout vorgestellt (Abbildung
+\ref{programlayoutfig}). Hier wurde vorgeschlagen ein Skript als
+Kontrollskript zu verwenden. Dieses kontrolliert den weiteren
+Programmablauf, ruft Funktionen auf, \"ubergibt Argumente und nimmt
+R\"uckgabewerte entgegen. Eine solche Struktur macht es einfach den
+Ablauf zu verstehen. Es bleibt aber die Frage, wie man das
+Kontrollskript unter den anderen \codeterm{m-files} als solches
+erkennt. Um dieses zu erleichtern gilt es zwei Dinge zu beachten:
+1. Wie werden Programme im Dateisystem organisiert? 2. Wie werden
+Programme benannt?
+
+Es hilft ungemein, wenn zusammengeh\"orige Skripte und Funktionen im
+gleichen Ordner auf der Festplatte zu finden sind. Es bietet sich also
+an f\"ur jede Analyse einen eigenen Ordner anzulegen und in diesem die
+zugeh\"origen \codeterm{m-files} abzulegen. Auf eine tiefere
+Schachtelung in weitere Unterordner kann in der Regel verzichtet
+werden. \matlab{} erzeugt einen ``MATLAB'' Ordner im eingenen
+``Documents'' (Linux) oder ``Eigene Dokumente'' (Windows) Ordner. Es
+bietet sich an diesen als Wurzelverzeichnis f\"ur eigene Arbeiten zu
+verwenden. Nat\"urlich kann auch jeder andere Ort gew\"ahlen
+werden. In dem Beispiel in Abbildung \ref{fileorganizationfig} wird
+innerhalb dieses Ordners f\"ur jedes Projekt ein eigener Unterordner
+erstellt in welchem widerum f\"ur jedes Problem, jede Analyse ein
+weitere Unterodner erstellt wird. In diesen liegen sowohl die
+ben\"otigten m-files also auch die Resultate der Analyse (Abbildungen,
+Dateien). Zu bemerken sind noch zwei weitere Dinge. Im Projektordner
+existiert ein Skript (analysis.m), das dazu gedacht ist, alle Analysen
+aufzurufen. Des Weiteren gitb es parallel zu den Projektordnern einen
+``functions'' Ordner in dem Funktionen liegen, die in mehr als einem
+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
+aktuellen Ordner nach passenden Dateien sucht (mehr Information in Box
+\ref{matlabpathbox}).
+
+\begin{figure}
+  \includegraphics[width=0.75\textwidth]{program_organization}
+  \titlecaption{\label{fileorganizationfig} M\"ogliche Oganisation von
+    Programmcode im Dateisystem.}{ F\"ur jedes Projekt werden
+    Unterordner f\"ur die einzelnen Analysen angelegt. Auf Ebene des
+    Projektes k\"onnte es ein Skript (hier ``analysis.m'') geben,
+    welches alle Analysen in den Unterordnern anst\"o{\ss}t.}
+\end{figure}
+
+
+\begin{ibox}[t]{\label{matlabpathbox}Der \matlab{} Suchpfad}
+
+  \begin{itemize}
+  \item Suchpfad, was soll das.
+  \item Reihenfolge.
+  \item \"Andern des Pfades.
+  \end{itemize}
+  
+  \includegraphics[width=0.75\textwidth]{search_path}
+\end{ibox}
+
+\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}
+
+
+  In verschiedenen Sprachen verschiedene Konventionen. In MATLAB ...
+  \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.
+  \end{itemize}
+
+
+\section{Namensgebung von Variablen und Konstanten}
+
+  \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

scientificcomputing-script.tex

@@ -27,6 +27,11 @@
 \lstset{inputpath=plotting/code/}
 \include{plotting/lecture/plotting}
 
+
+\graphicspath{{programmingstyle/lecture/}{programmingstyle/lecture/figures/}}
+\lstset{inputpath=programmingstyle/code/}
+\include{programmingstyle/lecture/programmingstyle}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \part{Grundlagen der Datenanalyse}