Minor change
[u/philim/db2osl_thesis.git] / program_code.tex
index 56d7028..6c83ce8 100644 (file)
@@ -29,8 +29,8 @@ name by 7 characters or about 26 \% is really not a problem.
 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.
@@ -43,9 +43,11 @@ implementations, for example, were optically separated this way.
 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
@@ -75,14 +77,14 @@ on the concepts of bootstrapping rather than details of the present code.
 
 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
@@ -96,7 +98,7 @@ are the following methods from \file{Column.java}:
 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,
@@ -115,14 +117,18 @@ also yields the desired result, \code{true}, since the change,
 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}.
@@ -140,8 +146,8 @@ As described in section \fullref{speaking}, class names were chosen to be concis
 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.
@@ -150,13 +156,17 @@ objects, could most often be avoided.
 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,
@@ -208,6 +218,7 @@ counterparts via downcasting (only), thereby giving a strong hint to
 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
@@ -233,8 +244,8 @@ Introducing artificial interfaces for the standalone classes was considered
 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.