diff --git a/Makefile b/Makefile index 1fcb26f..2038f42 100644 --- a/Makefile +++ b/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 diff --git a/programmingstyle/lecture/Makefile b/programmingstyle/lecture/Makefile new file mode 100644 index 0000000..ad1b36a --- /dev/null +++ b/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 + + diff --git a/programmingstyle/lecture/beamercolorthemetuebingen.sty b/programmingstyle/lecture/beamercolorthemetuebingen.sty new file mode 100644 index 0000000..c4a5da6 --- /dev/null +++ b/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 + +\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 + diff --git a/programmingstyle/lecture/figures/program_organization.png b/programmingstyle/lecture/figures/program_organization.png new file mode 100644 index 0000000..56a7a98 Binary files /dev/null and b/programmingstyle/lecture/figures/program_organization.png differ diff --git a/programmingstyle/lecture/figures/search_path.png b/programmingstyle/lecture/figures/search_path.png new file mode 100644 index 0000000..d78192f Binary files /dev/null and b/programmingstyle/lecture/figures/search_path.png differ diff --git a/programmingstyle/lecture/programmingstyle-chapter.tex b/programmingstyle/lecture/programmingstyle-chapter.tex new file mode 100644 index 0000000..fffe3a4 --- /dev/null +++ b/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} + diff --git a/programmingstyle/lecture/programmingstyle.tex b/programmingstyle/lecture/programmingstyle.tex new file mode 100644 index 0000000..ca5e0bd --- /dev/null +++ b/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 diff --git a/scientificcomputing-script.tex b/scientificcomputing-script.tex index 7103672..3e883ac 100644 --- a/scientificcomputing-script.tex +++ b/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}