From 87496d5f3d3ce2f27808b9ea4787f6d32aecdebf Mon Sep 17 00:00:00 2001 From: Jan Grewe Date: Sun, 15 Nov 2015 11:44:45 +0100 Subject: [PATCH] further typo fixes --- programmingstyle/code/calculate_sines.m | 6 +- programmingstyle/lecture/programmingstyle.tex | 65 ++++++++++--------- 2 files changed, 37 insertions(+), 34 deletions(-) diff --git a/programmingstyle/code/calculate_sines.m b/programmingstyle/code/calculate_sines.m index cd69b76..05ad1ca 100644 --- a/programmingstyle/code/calculate_sines.m +++ b/programmingstyle/code/calculate_sines.m @@ -2,9 +2,9 @@ function sines = calculate_sines(x, amplitudes, frequencies) % Function calculates sinewaves with all combinations of % given amplitudes and frequencies. % Arguments: x, a vector of radiants for which the sine should be - % computed - % amplitudes, a vector of amplitudes - % frequencies, a vector of frequencies + % computed. + % amplitudes, a vector of amplitudes. + % frequencies, a vector of frequencies. % % Returns: a 3-D Matrix of sinewaves, 2nd dimension represents % the amplitudes, 3rd the frequencies. diff --git a/programmingstyle/lecture/programmingstyle.tex b/programmingstyle/lecture/programmingstyle.tex index 03be2a6..0807c9d 100644 --- a/programmingstyle/lecture/programmingstyle.tex +++ b/programmingstyle/lecture/programmingstyle.tex @@ -37,23 +37,24 @@ 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 +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 eigenen -\file{Documents} (Linux) oder \file{Eigene Dokumente} (Windows) Ordner. Es -bietet sich an, diesen Ordner als Wurzelverzeichnis f\"ur eigene Arbeiten zu -verwenden. Nat\"urlich kann auch jeder andere Ort gew\"ahlen -werden. In dem Beispiel in \figref{fileorganizationfig} wird +\file{Documents} (Linux) oder \file{Eigene Dokumente} (Windows) +Ordner. Es bietet sich an, diesen Ordner als Wurzelverzeichnis f\"ur +eigene Arbeiten zu verwenden. Nat\"urlich kann auch jeder andere Ort +gew\"ahlt werden. In dem Beispiel in \figref{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 \codeterm{m-files} also auch die Resultate der Analyse (Abbildungen, -Daten-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 -\file{functions}-Ordner in dem Funktionen liegen, die in mehr als einem -Projekt oder einer Analyse gebraucht werden. +erstellt, in welchem wiederum f\"ur jedes Problem, jede Analyse ein +weiterer Unterodner erstellt wird. In diesen liegen sowohl die +ben\"otigten \codeterm{m-files} also auch die Resultate der Analyse +(Abbildungen, Daten-Dateien). Zu bemerken sind noch zwei weitere +Dinge. Im Projektordner existiert ein Skript (analysis.m), das dazu +gedacht ist, alle Analysen aufzurufen. Des Weiteren gibt es parallel +zu den Projektordnern einen \file{functions}-Ordner in dem Funktionen +liegen, die in mehr als einem Projekt oder einer Analyse gebraucht +werden. Beim Betrachten dieses Layouts f\"allt auf, dass es sehr wahrscheinlich ist, dass bestimmte Namen f\"ur Funktionen und Skripte @@ -65,7 +66,7 @@ aktuellen Ordner nach passenden Dateien sucht (mehr Information zum \begin{figure}[tp] \includegraphics[width=0.75\textwidth]{program_organization} - \titlecaption{\label{fileorganizationfig} M\"ogliche Oganisation von + \titlecaption{\label{fileorganizationfig} M\"ogliche Organisation 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, @@ -106,8 +107,8 @@ aktuellen Ordner nach passenden Dateien sucht (mehr Information zum \section{Namensgebung von Funktionen und Skripten} -\matlab{} sucht Funktionen und Skripte ausschlie{\ss}lich anhand der -Namen. Dabei spielt die Gro{\ss}- und Kleinschreibung eine Rolle. Das +\matlab{} sucht Funktionen und Skripte ausschlie{\ss}lich anhand des +Namens. Dabei spielt die Gro{\ss}- und Kleinschreibung eine Rolle. Das hei{\ss}t, dass die beiden Dateien \file{test\_funktion.m} und \file{Test\_funktion.m} zwei unterschiedliche Funktionen benennen k\"onnen. Diese Art der Variation des Namens ist nat\"urlich nicht @@ -127,9 +128,10 @@ aus dem Namen ein R\"uckschluss auf den Zweck ziehen lassen sollte. die beste Dokumentation. \end{important} -\matlab{} macht keine weiteren Vorgaben, was die Namen -angeht. Allerdings folgt die Benennung der vordefinierten Funktionen -gewissen Mustern: +In Namen verbietet \matlab{} verbietet Leerzeichen, Sonderzeichen und +Umlaute. Namen d\"urfen auch nicht mit Zahlen anfangen. Es mach f\"ur +die Namensgebung selbst keine weiteren Vorgaben. Allerdings folgt die +Benennung der in \matlab{} vordefinierten Funktionen gewissen Mustern: \begin{itemize} \item Namen werden immer klein geschrieben. \item Es werden gerne Abk\"urzungen eingesetzt (z.B. \code{xcorr} @@ -145,8 +147,7 @@ Anf\"ange zusammengesetzter Worte jeweils gro{\ss} geschrieben werden oder auch die Verwendung von Unterstrichen zur Trennung von Namenskomponenten. Eine Funktion, die die Anzahl von Aktionspotentialen bestimmt k\"onnte etwa \file{spikeCount.m} oder -\file{spike\_count.m} benannt werden. Leerzeichen, Sonderzeichen -oder Anf\"ange mit Zahlen sind in Namen nicht erlaubt. +\file{spike\_count.m} benannt werden. \section{Namensgebung von Variablen und Konstanten} @@ -183,9 +184,9 @@ Die Lesbarkeit von Programmen wird sehr durch den Codestil beeinflusst. Ein Programm, in dem z.B. Schleifenk\"orper nicht (oder zuf\"allig) einger\"uckt sind ist deutlich schwerer zu lesen und zu verstehen, als eines, in dem eine konsistente Einr\"uckung vorgenommen -wurde. Mit der Tastenkombination \keycode{Ctrl-I} % XXX Oder wie war das? XXX -kann ein markierter -Bereich im \matlab{} Editor automatisch richtig einger\"uckt werden. +wurde. Mit der Tastenkombination \keycode{Ctrl-I} (\keycode{Strg-I} +auf der deutschen Tastatur) kann ein markierter Bereich im \matlab{} +Editor automatisch richtig einger\"uckt werden. Sparsam und konsistent eingef\"ugte einzelne Leerzeilen sind hervorragend geeignet, um logische Abschnitte eines Programm zu @@ -220,6 +221,8 @@ end end \end{lstlisting} +\clearpage + \begin{lstlisting}[label=cleancode, caption={\"Ubersichtliche Implementation des Random-walk.}] num_runs = 10; max_steps = 1000; @@ -246,10 +249,10 @@ sind kurze Kommentare, die den Zweck und das Ziel eines Abschnitts im Programm erl\"autern (z.B. \code{\% compute mean firing rate over all trials}). -Zu viele Kommentare k\"onnen in der Entwicklungsphase eines Programms -sehr hilfreich sein, bl\"ahen aber den Code auf. Durch die Verwendung -guter Variablen- und Funktionsnamen sollten die meisten Zeilen sowieso -weitestgehend selbsterkl\"arend sein. +Viele und h\"aufige Kommentare k\"onnen in der Entwicklungsphase eines +Programms sehr hilfreich sein, bl\"ahen aber den Code auf. Durch die +Verwendung guter Variablen- und Funktionsnamen sollten die meisten +Zeilen sowieso weitestgehend selbsterkl\"arend sein. Die beste Dokumentation ist der Code selbst. Gut geschriebener Code mit ausdrucksstarken Variablen- und Funktionsnamen ben\"otigt keine @@ -317,7 +320,7 @@ Das Auslagern von Funktionalit\"at in eigene Funktionen f\"uhrt dazu, dass eine F\"ulle von Dateien erzeugt wird, die die \"Ubersichtlichkeit nicht unbedingt erh\"oht. Wenn die auszulagernde Funktionalit\"at an vielen Stellen ben\"otigt wird ist es -dennoch sinnvol dies zu tun. Wenn nicht, dann bietet \matlab{} die +dennoch sinnvoll dies zu tun. Wenn nicht, dann bietet \matlab{} die M\"oglichkeit sogenannte \codeterm{lokale Funktionen} oder auch \codeterm{geschachtelte Funktionen} (\enterm{nested functions}) zu erstellen. Listing \ref{localfunctions} zeigt ein Beispiel f\"ur eine @@ -367,7 +370,7 @@ machen Programmiersprachen gibt es Traditionen und \"Ubereink\"unfte, diese sollten dann beachtet werden. Wiederholte Programmabschnitte sollten in Funktionen ausgelagert -werden. Wenn diese nich von globalem Interesse sind, kann mit +werden. Wenn diese nicht von globalem Interesse sind, kann mit \codeterm{lokalen} oder \codeterm{geschachtelten Funktionen} die \"Ubersichtlichkeit erh\"oht werden.