paper1.tex

\section{Coding Guidelines: Finding the Art in Science}
Das erste Paper, dass in dieser Arbeit behandelt wird, trägt den Titel \enquote{ Coding Guidelines: Finding the Art in Science, What separates good code from great code?} von Robert Green und Henry Ledgard\cite{Green}. Die Autoren versuchen eigene Regeln, für das entwickeln von Quelltext aufzustellen. Das Ziel ist es den Programmierer in die Lage zu versetzen, einen Quelltext zu schreiben der schnell und einfach von anderen Programmierern gelesen, verstanden und erweitert werden kann. Das schließt mit ein, dass sich der Entwickler, ohne Kenntnis des Systems, schnell im gesamten Quelltext zurechtfinden kann. Dies ist vor allem in großen, langlebigen Softwareprojekten von Nöten, da hier eine gewisse Fluktuation bei den Entwicklern nicht auszuschließen ist\cite[S. 12]{Green}.

Beim erstellen der Regeln wird nicht auf bestimmte Entwicklungsumgebungen oder andere Tools Rücksicht genommen. Die Regeln sollen mit allen Editoren angewandt werden können.
\subsection{Monospace and the ASCII}
Als erstes wird bezug auf den Artikel von Kamp\cite{Kamp} genommen. Dieser stellte fest wie wenig sich das Aussehen von Quelltexten im Laufe der Zeit geändert hat und wie sehr es noch dem Schreiben mit einer Schreibmaschine ähnelt. Es wurden zwar viele nützliche Programme entwickelt die beim erstellen von Quelltexten helfen können, trotzdem ist er immer noch in Textform. Noch dazu wird immer eine Monospace Schriftart zur Darstellung verwendet. Dazu kommt noch das es kein klassischer Fließtext ist. Der verwendete Wortschatz ist stark eingeschränkt und es werden häufig mathematische Darstellungsformen gewählt \cite[S. 2]{Green}. Darum wir im Paper\cite{Green} vorgeschlagen für Quelltext eine tabellenartige Formatierung zu wählen um die Lesbarkeit zu erhöhen. Ein Beispiel hierfür ist in Listing \ref{paper1:table} zu sehen. Die \enquote{\texttt{case}}, sowie die \enquote{\texttt{break}} Anweisungen befinden sich in einer Spalte und die Aufrufe für die einzelnen Verzweigungspfade befinden sich in einer Spalte.

\begin{listing}[H]
    \begin{minted}{c}
char c1;
c1 = getChoice();
switch(c1) {
    case 'q': case 'Q': quit();                 break;
    case 'e': case 'e': enterPerson(content);   break;
    case 'd': case 'd': delPerson(content);     break;
    case 's': case 's': sortByName();           break;
    case 'l': case 'l': showAll();              break;
    case 'f': case 'f': searchByName(content);  break;
    case default: System.out.println(
        "--Invalid Command!!\n");
}
    \end{minted}
    \caption{Beispiel für tabellarische Darstellung von Quelltext aus \cite[S. 2]{Green}}
    \label{paper1:table}
\end{listing}

\subsection{Naming}
\label{paper1:naming}
Als nächstes wenden Sich Robert Green und Henry Ledgard der Benennung von Elementen zu\cite[S. 3f.]{Green}. Die Benennung aller Elemente ist ein wichtiges belang bei der Entwicklung. Eine Sinnvolle Benennung hilft dem Leser eines Quelltextes sich in diesem zu Orientieren. Sie stellen hierzu die folgenden Regeln auf\cite[S. 4]{Green}:
\begin{itemize}
    \item Variablen- und Klassennamen sollen Nomen bzw. Nominalphrasen sein
    \item Klassennamen sind zusammenfassende Nomen (\texttt{Book})
    \item Variablennamen sind exakte beschreibende Nomen (\texttt{BookingNumber})
    \item Prozeduren sollten Verben bzw. Verbphrasen sein (\texttt{CalculateCost})
    \item Wertliefernde Methoden sollen Nomen Phrasen sein (\texttt{GetName})
    \item Boolesche Werte sollen Adjektive sein
    \item Für zusammengesetzte Namen sollte man sich an die englische Sprache halten
    \item Namen sollten aussprechbar sein
\end{itemize}

Auf diese weiße soll dem Leser zu jeder zeit klar sein, ob eine Operation, eine Variable oder eine Klasse hinter einem Namen steht. Die Namen sollen in einfachem Englisch gehalten sein.
Weiterhin sprechen sie an, dass das finden eines geeigneten Namen sehr schwierig sein kann. Ziel bei der Namensgebung soll sein, dass man aus ihnen die Konzepte der Software ablesen kann.

\subsection{Länge von Namen}
Bei der Namensgebung kann es sehr schnell dazu kommen, dass die Variablennamen lang werden. Um Namen aber kurz und prägnant zu halten soll der Kontext mit einbezogen werden. In Listing \ref{paper1:contextbasednames} ist ein Beispiel mit zu langen Namen zu sehen. Da sie zur Klasse \texttt{Circle} gehören, ist der \texttt{Circle}-Präfix überflüssig. Die Variablen gehören klar zur \texttt{Circle}-Klasse.
\cite[S. 4f.]{Green}
\begin{listing}[H]
    \begin{minted}{java}
class Circle {
    public Point circleCenter;
    public Point circleRadius;
}
    \end{minted}
    \caption{Beispiel für die Verkürzung von Variablennamen anhand des Kontextes}
    \label{paper1:contextbasednames}
\end{listing}
Green und Ledgard vertreten auch die These, dass besonders häufig genutzte Variablenamen sehr kurz sein sollen \cite[S. 6]{Green}, da dies mehr Klarheit schafft. Am besten sollte der Variablennamen lediglich aus einem Buchstaben bestehen.

\subsection{Struktur durch Whitespaces}
Der Quelltext soll durch Einrückung, Zeilenumbrüche und Leerzeilen strukturiert werden. Wie bereits besprochen kann man die Struktur und den Ablauf eines Programmes durch Einrückung hervorheben. Leerzeilen sollen nach \cite[S. 6f.]{Green} für die folgenden Zwecke eingesetzt werden:
\begin{itemize}
\item Beim Wechsel von vorbereitendem Quelltext, wie Variablendeklarationen, zu ausführenden Befehlen.
\item Vor und nach Klassen, Methoden und Funktionen
\item Um verschiedene logisch zusammenhängende Quelltextteile von einander abzugrenzen.
\end{itemize}
Ein Beispiel ist in Listing \ref{paper1:linebreaks} zu sehen. Dies ist ein Ausschnitt aus einem Lösungsansatz für das \enquote{Dining Philosophers Problem}\cite{Chandy}. Es sind drei, durch Leerzeilen getrennte Blöcke zu sehen. Es ist erkennbar, dass sich der erste Block Variablen vorbereitet, der Zweite die eigentlichen Ablauf durchführt und der Dritte die Rückgabe darstellt.
\begin{listing}[H]
\begin{minted}{c}
void* philo(void *args) {
    int *num = (int*) args;

    printf("%d hello\n", *num);
    while (1) {
        think(*num);
        eat(*num);
    }

    return NULL;
}
\end{minted}
\label{paper1:linebreaks}
\caption{Beispiel für den Einsatz von Leerzeilen zur Hervorhebung der Struktur}
\end{listing}

Leerzeilen können verschiedene logische Konstrukte voneinander abgrenzen. Auf Ebene der Zeilen kann ein Leerzeichen verwendet werden um, dass lesen zu erleichtern und die Struktur darzustellen.
Nach Green und Ledgrad\cite[S. 7]{Green} sollen Leerzeichen nach jedem Komma stehen, sowie vor und nach nicht unären Operatoren. Der Memberoperator \enquote{\texttt{.}} bildet die Ausnahme. Er wird ohne separierende Leerzeichen verwendet. Zwischen Variablen und unärem Operator darf kein Leerzeichen sein. Ein Beispiel dieser Regeln ist in Listing \ref{paper1:spaces} 

\begin{listing}[H]
    \begin{minted}{java}
int i = 1;
int j = input.get();
i++; --j;
return i * j;
    \end{minted}
    \label{paper1:spaces}
    \caption{Beispiel Leerzeichen zur Trennung von Operationen}
\end{listing}

Zuletzt wird in \cite{Green} noch eingeräumt, dass es Sinn machen kann, wie in Listing \ref{paper1:spaces}, Zwei Befehle in eine Zeile zu schreiben.

\subsection{Struktur durch Einrückung}
Einrückung kann ein gutes Hilfsmittel sein um dem Leser beim verstehen von Quelltexten zu helfen. Nach \cite[S. 8]{Green} sollte bei einfachen Bedingungen die Klammerung weggelassen werden. Siehe dazu Listing \ref{paper1:withoutbraces}. Durch die Einrückung soll die Struktur deutlich werden, welcher Befehl gehört zu welcher Methode, welche Methode zu welcher Klasse, etc.

\begin{listing}[H]
    \begin{minted}{c}
if (result >= 90)
    cout << "Grade of A!";
else if (result >= 80)
    cout << "Grade of B";
else if (result >= 70)
    cout << "Sorry, grade of C";
else
    cout << "Not very good";
    \end{minted}
    \label{paper1:withoutbraces}
    \caption{Beispiel für sich ausschließende Verzweigung ohne Blockklammern aus \cite[S. 8]{Green}.}
\end{listing}

Wenn man bei langen Zeilen gezwungen ist, im Befehl einen Zeilenumbruch einzufügen, wird in \cite[S. 3]{Green} vorgeschlagen, dass die zweite Zeile entweder um eine Ebene eingerückt oder ausgerückt wird.

\subsection{Kommentare}
Green und Ledgard schreiben, dass Kommentare mit Bedacht eingesetzt werden sollen. Das Hauptaugenmerk soll auf dem Quelltext liegen, nicht auf den Kommentaren. Der Quelltext soll so geschrieben sein, dass seine Intention klar erkennbar ist. Bei einem solchen Quelltext ist es nicht nötig viele Kommentare zu verwenden. Kommentare sollen als zusätzliches Medium für die Kommunikation zwischen Autor und Leser des Quelltextes dienen und nur dann verwendet werden wenn es nicht möglich ist den Quelltext so klar zu gestallten, dass klar zu erkennen ist was er bezweckt. \cite[S. 9]{Green}


\subsection{Bewertung}

Das man eine Monospace Schriftart zum Schreiben eines Quelltextes verwendet ist keine neue Erkenntnis. Nur so lässt sich die Struktur des Quelltextes durch Einrückung darstellen. Auch tabellenartige Strukturen sind möglich. Eine Tabellenstruktur birgt aber verschiedene Nachteile. Wenn man dies auf eine \enquote{\texttt{Switch-Case}} Anweisung, wie in Listing \ref{paper1:table} anwendet und bei einer späteren Änderung des Quelltextes mehr als ein Befehl pro Zeile ausgeführt werden soll wird diese Struktur schnell sehr breit. Hinzu kommt bei allen Tabellenstrukturen, dass  Veränderungen häufig sehr schreibintensiv sind. Stelle man sich eine \enquote{\texttt{Switch-Case}} Anweisung vor, die viele verschiedene Fälle abdeckt. Fügen wir einen neuen hinzu, deren Methodenaufruf länger ist als die bereits vorhandenen Aufrufe, muss man die anderen Zeilen der Tabelle anpassen.

Die Richtlinien für Variablennamen funktionieren gut. Sie erfüllen klar ihren Zweck. Lediglich eine Erwähnung wie zusammengesetzte Variablennamen zu schreiben sind fehlt. In den Beispielen wurde immer eine \enquote{CamelCase} Variante gewählt. Der Variablenname \enquote{GetName} ließe sich auch als \enquote{Get\_Name} schreiben und hat eine äquivalente Bedeutung. Wenn nun verschiedene Entwickler am Quelltext arbeiten und der eine mit unterstrichen, der andere aber mit der \enquote{CamelCase} schreibweiße arbeitet wird der Quelltext schnell inkonsistent und wirkt nicht mehr einheitlich. Damit wäre das Ziel solcher vorgaben zunichte gemacht. Die Art der Schreibweiße sollte festgelegt sein, damit diese im gesamten Quelltext einheitlich ist.

Bei der Länge von Variablennamen wurde gesagt, dass diese so kurz wie möglich, bei häufig verwendeten Objekten bzw. Funktionen sogar lediglich ein Zeichen. Gute Variablennamen zu finden ist eine Kunst für sich. Ein Variablenname sollte klar wiederspiegeln was es für eine Variable ist. Für globale, häufig verwendete Elemente gilt dies besonders, aber ein einzelnes Zeichen ist nicht aussagekräftig genug. Wenn man eine Klasse erstellt die einen Vektor beschreibt sollte diese nicht \texttt{V} heißen sondern \texttt{Vector}. Namen die lediglich aus einem Zeichen bestehen sollten nur für Elemente verwendet werden, die lediglich in einem kurzen Ausschnitt des Quelltextes verwendet werden. Üblicherweise gehören hierzu Zählvariablen in Iterationen.

Wie in \cite[S. 3, 6-8]{Green} gut beschrieben ist sind Zeilenumbrüche und Leerzeichen bzw. Tabulatoren ein wichtiges Mittel um den Quelltext lesbar zu gestallten. Verzweigungen und Strukturen lassen sich durch Einrückungen verdeutlichen und logisch zusammenhängende Blöcke unterteilen. Lediglich das weglassen von Blockklammern für Anweisungen innerhalb von \enquote{\texttt{if}}-Blöcken kann sich negativ auswirken. Wenn bei Änderungen am Quelltext aus der einen Anweisung mehrere werden müssen die Blockklammern ergänzt werden, ist dabei zu verschmerzen. Es können sich so aber schnell Fehler einschleichen, die schwer zu finden sind. Wenn man beim Schreiben einer solchen  Anweisung versehentlich hinter dem \enquote{\texttt{if}} ein Semikolon einfügt, wird der Quelltext weiterhin Kompilieren und sich ausführen lassen, die Einrückung suggeriert eine Verschachtelung, die aber nicht stattfindet, weil der \enquote{\texttt{if}} Block leer ist. Beispielhaft ist dies in Listing \ref{paper1:semicolonif} zu sehen. Die Operation \enquote{\texttt{buy()}} wird immer aufgerufen.

\begin{listing}[H]
    \begin{minted}{c}
if (action == "buy");
    buy();
    \end{minted}
    \label{paper1:semicolonif}
    \caption{Beispiel für eine fehlerhafte Verzweigung, ohne Blockklammern. \cite[S. 8]{Green}.}
\end{listing}

Bei Kommentaren im Quelltext beschreiben Green  und Ledgard richtig, dass Kommentare lediglich sparsam und mit Bedacht eingesetzt werden sollen\cite[S. 9]{Green}. Guter Quelltext sollte genau dies erfüllen. Er sollte gelesen werden können und ohne Kommentare verstanden werden. Dies gestaltet sich manchmal jedoch als schwierig. An solchen Stellen ist ein Kommentar ein legitimes Mittel um dem Leser eine Hilfe zu sein.