More generally, ``speaking code'' was used wherever possible,
as described in section \fullref{speaking},
which rendered many uses of comments unnecessary.
-In fact, the number of (plain, e.g. non-\name{Javadoc}) comments was consciously minimized,
-to enforce speaking code and avoid redundancy.
+In fact, the number of (plain, e.g. non-\name{Javadoc}) comments was
+consciously minimized, to enforce speaking code and avoid redundancy.
This technique is known TODO.
An exception of course from this is the highlighting of subdivisions.
Another alternative would have been to use separate methods for this code
pieces, as was done in other cases, and thereby sticking strictly to the so-called
``Composed Method Pattern'' \cite{composed}.
-However, this would have introduced additional artifacts with either long or non-speaking names,
+However, sticking to this pattern too rigidly would have introduced additional
+artifacts with either long or non-speaking names,
would have interrupted the reading flow and also would have increased complexity,
-because these methods would have been callable at least from everywhere in the source file.
+because these methods would have been callable at least from everywhere
+in the source file.
Wherever possible, the appropriate \name{Javadoc} comments were used in favor of
plain comments, for example to specify parameters, return types, exceptions
In fact, carefully avoiding the introduction of technical artifacts to mind,
preventing programmers from focusing on the actual program logic,
-is an important principle of writing clean code TODO.
+is an important principle of writing clean code \cite{str4}.
In modern programming languages, of course the main instruments for achieving
this are the type system and exceptions.
In particular, static type information should be used to reflect data
abstraction and the ``kind'' of data, an object reflects,
while dynamic type information should only be used implicitly,
-through dynamically dispatching method invocations\cite{str4}.
+through dynamically dispatching method invocations \cite{str4}.
Exceptions on the other hand should be used at any place related to errors
and error handling, separating error handling noticeably from other code and
enforcing the treatment of errors, preventing the programmer from using
There return type is the \name{Java} class \code{Boolean}, not the plain type
\code{boolean}, because the information they return is not always known.
In an early stage of the program, they returned \code{boolean} and were
-accompanied TODO by two methods
+accompanied by two methods
\code{public boolean knownIsNonNull()} and \code{public boolean knownIsUnique()},
telling the caller whether the respective information was known and thus the
value returned by \code{isNonNull()} or \code{isUnique()}, respectively,
even when the programmer forgets that he deals with objects.
However, when comparing two return values of one of the methods in general
-- as opposed to comparing one such return value against a constant --,
-errors could occur if the programmer writes \code{col1.isUnique() == col2.isUnique()}
+errors could occur if the programmer mistakenly writes \code{col1.isUnique() == col2.isUnique()}
instead of \code{col1.isUnique().booleanValue() == col2.isUnique().booleanValue()}.
-\\TODO: Java rules.
+In this case, since the two \code{Boolean} objects are compared for identity \cite{java},
+the former comparison can return \code{false}, even when the two boolean values are in fact
+the same.
+However, since this case was considered much less common than cases in which the other
+solution could make programmers making mistakes produce undetected errors, it was preferred.
-TODO: more, summary
+TODO: more (?), summary
\subsection{Classes}
-\label{classes}
+\label{code_classes}
Following the object-oriented programming paradigm, classes were heavily used
to abstract from implementation details and to yield intuitively usable objects with
a set of useful operations \cite{obj}.
but nevertheless expressive TODO.
\name{Java} packages were used to help attain this aim,
which is why the previously mentioned class names are unambiguous
-(for details about package use, see section \fullref{packages}, for the description
-of the packages in \myprog{} and their structuring, see section \fullref{coarse}).
+(for details about package use, see section \fullref{code_packages}, for the description
+of the packages themselves and their structuring, see section \fullref{coarse}).
Care was taken not to introduce unnecessary classes, thereby complicating
code structure and increasing the number of source files and program entities.
On the other hand of course, it usually is not the cleanest solution
to avoid such artificial classes entirely.
+Section \fullref{hierarchies} describes how the classes of \myprog{} are organized
+into class hierarchies.
+
\subsubsection{Const correctness}
+\label{const}
Specifying in the code which objects may be altered and which shall remain constant,
thus allowing for additional static checks preventing undesired modifications,
is commonly referred to as ``const correctness'' TODO.
Unfortunately, \name{Java} lacks a keyword like \name{C++}'s \code{const},
-making it harder to achieve const correctness.
+making it harder to achieve const correctness \cite{final}.
It only specifies the similar keyword \code{final}, which is much less expressive and
doesn't allow for a similarly effective error prevention \cite{final}.
In particular, because \code{final} is not part of an object's type information,
programmers that the resulting objects are to be used with care.
\subsubsection{Java interfaces}
+\label{code_interfaces}
In \name{Java} programming, it is quiet common and often recommended, that every
class has at least one \code{interface} it \code{implements},
specifying the operations the class provides. TODO
unnecessary at least, if not messy.
\subsection{Packages}
-\label{packages}
-As mentioned in section \fullref{classes}, class names were chosen to be
+\label{code_packages}
+As mentioned in section \fullref{code_classes}, class names were chosen to be
concise but nevertheless expressive.
This only was possible through the use of \name{Java} \code{package}s,
which also helped structure the program.