[translation] functions, half way done

programming/lecture/programming.tex

@@ -1322,94 +1322,100 @@ works as intended. A solution for this problem are the
 
 \subsection{Functions}
 
-Eine Funktion in \matlab{} wird \"ahnlich zu einer mathematischen
-Funktion definiert:
-\[ y = f(x) \]
-Die Funktion hat einen Namen $f$, sie \"uber das Argument $x$
-einen Input und liefert ein Ergebnis in $y$ zur\"uck. Listing
-\ref{functiondefinitionlisting} zeigt wie das in \matlab{} umgesetzt
-wird.
-
-\begin{lstlisting}[caption={Funktionsdefinition in \matlab{}}, label=functiondefinitionlisting]
+Functions in \matlab{} are similar to a mathematical functions 
+\[ y = f(x) \] Here, the mathematical function has the name $f$ and it
+has one \codeterm{argument} $x$ that is transformed into the
+function's output value $y$. In \matlab{} the syntax of a function
+declaration is very similar (listing~\ref{functiondefinitionlisting}).
+
+\begin{lstlisting}[caption={Declaration of a function in \matlab{}}, label=functiondefinitionlisting]
 function [y] = functionName(arg_1, arg_2)
 %         ^                  ^       ^
-%  Rueckgabewert        Argument_1, Argument_2
+% return value        argument_1, argument_2
 \end{lstlisting}
 
-Ein Funktion beginnt mit dem Schl\"usselwort \code{function} gefolgt
-von den R\"uckgabewerte(n), dem Funktionsnamen und (in Klammern) den
-Argumenten.  Auf den Funktionskopf folgt der auszuf\"uhrende
-Programmcode im Funktionsk\"orper. Die Funktionsdefinition wird
-% optional  %XXX es ist vielleicht optional, aber gute stil ware es immer hinzuschreiben, oder?
- mit einem \code{end} abgeschlossen. Jede Funktion, die vom
-Nutzer direkt verwendet werden soll, ist in einer eigenen Datei
-definiert. \"Uber die Definition/Benutzung von Funktionen wird folgendes erreicht:
+The keyword \code{function} is followed by the return value(s) (it can
+be a list \code{[]} of values), the function name and the
+argument(s). The function head is then followed by the function's
+body. A function is ended by and \code{end} (this is in fact optional
+but we will stick to this). Each function that should be directly used
+by the user (or called from other programs) should reside in an
+individual \code{m-file} that has the same name as the function. By
+using functions instead of scripts we gain several advantages:
 \begin{itemize}
-\item Kapseln von Programmcode, der f\"ur sich eine Aufgabe l\"ost.
-\item Definierte Schnittstelle.
-\item Eigener G\"ultigkeitsbereich:
+\item Encapsulation of program code that solves a certain task. It can
+  be easily re-used in other programs.
+\item There is a clear definition of the function's interface. What
+  does the function need (the arguments) and what does it return (the
+  return values).
+\item Separated scope:
   \begin{itemize}
-  \item Variablen im Workspace sind in der Funktion \emph{nicht} sichtbar.
-  \item Variablen, die in der Funktion definiert werden erscheinen
-    \emph{nicht} im Workspace.
+  \item Variables that are defined within the function do not appear
+    in the workspace and cannot cause any harm there.
+  \item Variables that are defined in the workspace are not visible to
+    the function.
   \end{itemize}
-\item Erh\"oht die Wiederverwendbarkeit von Programmcode.
-\item Erh\"oht die Lesbarkeit von Programmen, da sie
-  \"ubersichtlicher werden.
+\item Functions increase re-usability.
+\item Increase the legibility of programs since they are more clearly
+  arranged.
 \end{itemize}
 
-Das Folgende Beispiel (Listing \ref{badsinewavelisting}) zeigt eine
-Funktion, die eine Reihe von Sinusschwingungen unterschiedlicher
-Frequenzen berechnet und graphisch darstellt.
-
-\begin{lstlisting}[caption={Ein schlechtes Beispiel einer Funktion, die eine Reihe Sinusse plottet.},label=badsinewavelisting]
-function meineErsteFunktion() % Funktionskopf
-   t = (0:0.01:2); % hier faengt der Funktionskoerper an
-   frequenz = 1.0;
-   amplituden = [0.25 0.5 0.75 1.0 1.25];
-   for i = 1:length(amplituden)
-       y = sin(frequenz * t * 2 * pi) * amplituden(i);
+The following listing (\ref{badsinewavelisting}) shows a function that
+calculates and displays a bunch of sines with different amplitudes.
+
+
+\begin{lstlisting}[caption={Bad example of a function that displays a series of sines.},label=badsinewavelisting]
+function meineFirstFunction() % function head
+   t = (0:0.01:2); 
+   frequency = 1.0;
+   amplitudes = [0.25 0.5 0.75 1.0 1.25];
+   for i = 1:length(amplitudes)
+       y = sin(frequency * t * 2 * pi) * amplituden(i);
        plot(t, y)
        hold on;
    end 
 end
 \end{lstlisting}
-Das obige Beispiel ist ein Paradebeispiel f\"ur eine schlechte
-Funktion. Sie hat folgende Probleme:
+
+\code{myFirstFunction} (listing~\ref{badsinewavelisting}) is a
+prime-example of a bad function. There are several issues with it's
+design:
+
 \begin{itemize}
-\item Der Name ist nicht aussagekr\"aftig.
-\item Die Funktion ist f\"ur genau einen Zweck geeignet.
-\item Was sie tut, ist festgelegt und kann von au{\ss}en nicht
-  beeinflusst oder bestimmt werden.
-\item Sie tut drei Dinge auf einmal: Sinus berechnen \emph{und}
-  Amplituden \"andern \emph{und} graphisch darstellen.
-\item Es ist nicht (einfach) m\"oglich an die berechneten Daten zu
-  kommen.
-\item Keinerlei Dokumentation. Man muss den Code lesen und rekonstruieren, was sie tut.
+\item The function's name does not tell anything about it's purpose.
+\item The function is made for exactly one use-case (frequency of
+  1\,Hz and five amplitudes).
+\item The function's behavior is \enterm{hard-coded} within it's body
+  and cannot be influenced without changing the function itself.
+\item It solves three tasks at the same time: calculate sine
+  \emph{and} change the amplitude \emph{and} plot the result.
+\item There is no way to access the calculated data.
+\item No documentation. One has to read and understand the code to
+  learn what is does.
 \end{itemize}
 
-Bevor wir anfangen die Funktion zu verbessern mu{\ss} definiert werden
-was das zu l\"osende Problem ist:
+Before we can try to improve the function the task should be clearly
+defined:
 \begin{enumerate}
-\item Welches Problem soll gel\"ost werden?
-\item Aufteilen in Teilprobleme. 
-\item Gute Namen finden.
-\item Definieren der Schnittstellen --- Was m\"ussen die beteiligten Funktionen
-  wissen? Was sollen sie zur\"uckliefern?
-\item Daten zur\"uck geben (R\"uckgabewerte definieren). 
+\item Which problem should be solved?
+\item Can the problem be subdivided into smaller tasks?
+\item Find good names for each task.
+\item Define the interface. Which information is necessary to solve
+  each task and which results should be returned to the caller
+  (e.g. the user of another program that calls a function)?
 \end{enumerate}
-Das Beispielproblem aus Listing \ref{badsinewavelisting} kann in drei
-Teilprobleme aufgetrennt werden. (i) Berechnen der \emph{einzelnen}
-Sinusse. (ii) Plotten der jeweils berechneten Daten und (iii)
-Koordination von Berechnung und Darstellung mit unterschiedlichen
-Amplituden. 
-
-\paragraph{I. Berechnung eines einzelnen Sinus}
-
-Die Berechnung eines einzelnen Sinus ist ein typischer Fall f\"ur eine
-Funktion. Wiederum macht man sich klar, (i) wie die Funktion
-hei{\ss}en soll, (ii) welche Information sie ben\"otigt und (iii)
-welche Daten sie zur\"uckliefern soll. 
+
+As indicated above the \code{myFirstFunction} does three things at
+once, it seems natural, that the task should be split up into three
+parts. (i) Calculation of the individual sine-wave defined by the
+frequency and the amplitude (ii) graphical display of the data and
+(iii) coordination of calculation and display.
+
+\paragraph{I. Calculation of a single sine-wave}
+
+Before we start coding it is best, to again think about the task and
+define (i) how to name the function, (ii) which information it needs
+(arguments), and (iii) what it should return to the caller.
 
 \begin{enumerate}
 \item \codeterm[Funktion!Name]{Name}: der Name sollte beschreiben, was