Minor change
[u/philim/db2osl_thesis.git] / program_code.tex
index 223d7a7..56d7028 100644 (file)
@@ -29,26 +29,25 @@ 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-Javadoc) comments was consciously minimized,
+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.
 In class and method implementations, comments like
-\codepar{//********************** Constructors **********************TODO}
+\codepar{//********************** Constructors **********************\textbackslash\textbackslash}
 
 were deliberately used to ease navigation inside source files for unfamiliar
 readers, but also to enhance readability: independent parts of method
 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, but this would then have introduced
-additional artifacts with either long or non-speaking names.
-Additionally, it would have increased complexity, because these methods
-would have been callable at least from everywhere in the source file,
-and would have interrupted the reading flow.
-This technique is known TODO, while TODO
-
-Wherever possible, appropriate Javadoc comments were used in favor of
+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,
+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.
+
+Wherever possible, the appropriate \name{Javadoc} comments were used in favor of
 plain comments, for example to specify parameters, return types, exceptions
 and links to other parts of the documentation.
 
@@ -94,7 +93,7 @@ in combination, while cleanly fitting into the context of dynamic dispatching,
 are the following methods from \file{Column.java}:
 \codepar{public Boolean isNonNull()\\public Boolean isUnique()}
 
-There return type is the Java class \code{Boolean}, not the plain type
+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
@@ -103,11 +102,11 @@ telling the caller whether the respective information was known and thus the
 value returned by \code{isNonNull()} or \code{isUnique()}, respectively,
 was reliable.
 
-They were then changed to return the Java class \code{Boolean} and to return
+They were then changed to return the \name{Java} class \code{Boolean} and to return
 null pointers in case the respective information is not known.
 This eliminated any possibility of using unreliable data in favor of generating
 exceptions instead, in this case a \code{NullPointerException}, which is thrown
-automatically by the Java Runtime Environment if the programmer forgets the
+automatically by the \name{Java Runtime Environment} if the programmer forgets the
 null check and tries to get a definite value from one of these methods
 when the correct value currently is not known.
 
@@ -130,7 +129,7 @@ a set of useful operations \cite{obj}.
 
 \subsubsection{Identification of classes}
 To identify potential classes, entities from the problem domain were -- if reasonable --
-directly represented as Java classes.
+directly represented as \name{Java} classes.
 The approach of choosing ``the program that most directly models the aspects of the
 real world that we are interested in'' to yield clean code,
 as described and recommended by Stroustrup \cite{str3}, proved to be extremely useful
@@ -139,8 +138,10 @@ As a consequence, the code declares classes like \code{Column}, \code{ColumnSet}
 \code{ForeignKey}, \code{Table}, \code{TableSchema} and \code{SQLType}.
 As described in section \fullref{speaking}, class names were chosen to be concise
 but nevertheless expressive TODO.
-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}).
+\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}).
 
 Care was taken not to introduce unnecessary classes, thereby complicating
 code structure and increasing the number of source files and program entities.
@@ -150,12 +151,12 @@ On the other hand of course, it usually is not the cleanest solution
 to avoid such artificial classes entirely.
 
 \subsubsection{Const correctness}
-Specifying in the code which objects may be altered and which shall remain constant, thus
-allowing for additional static checks preventing undesired modifications,
+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, Java lacks a keyword like C++'s \code{const}, making it harder to
-achieve const correctness.
+Unfortunately, \name{Java} lacks a keyword like \name{C++}'s \code{const},
+making it harder to achieve const correctness.
 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,
@@ -175,7 +176,7 @@ Several possibilities were considered to address this problem:
        \item Giving the methods which modify object states special names
        like\\\code{setName\textendash\textendash USE\_WITH\_CARE}
        \item Delegating changes of objects to special ``editor'' objects to be
-       obtained when an object shall be altered
+       obtained when an object shall be altered TODO
        \item Deriving classes offering the modifying methods from the read-only
        classes
 \end{itemize}
@@ -207,8 +208,8 @@ counterparts via downcasting (only), thereby giving a strong hint to
 programmers that the resulting objects are to be used with care.
 
 \subsubsection{Java interfaces}
-In Java programming, it is quiet common and often recommended, that every
-class has at least one \code{interface} it \code{implemen,ts},
+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
 If no obvious \code{interface} exists for a class or the desired
 interface name is already given to some other entity,
@@ -226,7 +227,7 @@ So, except from the standalone classes, an interface existed anyway, either
 ``naturally'' (as in the case of \code{Key}, for example) or because of
 the chosen way to implement const correctness.
 In some cases, these were interfaces declared in the program code, while
-in some cases, Java interfaces like \code{Set} were implemented
+in some cases, \name{Java} interfaces like \code{Set} were implemented
 (an obvious choice, of course, for \code{ColumnSet}).
 Introducing artificial interfaces for the standalone classes was considered
 unnecessary at least, if not messy.
@@ -235,13 +236,13 @@ unnecessary at least, if not messy.
 \label{packages}
 As mentioned in section \fullref{classes}, class names were chosen to be
 concise but nevertheless expressive.
-This only was possible through the use of Java \code{package}s,
+This only was possible through the use of \name{Java} \code{package}s,
 which also helped structure the program.
 
 For the current, relatively limited, extent of the program which currently
 comprises $45$ (\code{public}) classes, a flat package structure was
 considered ideal, because it is simple and doesn't stash source files deep
-in subdirectories (in Java, the directory structure of the source tree
+in subdirectories (in \name{Java}, the directory structure of the source tree
 is required to reflect the package structure TODO).
 Because also every class belongs to a package,
 each source file is to be found exactly one directory below the root
@@ -249,8 +250,8 @@ program source directory, which in many cases eases their handling.
 
 The following $11$ packages exist in the program
 (their purpose and more details about the package structure are
-described in section TODO):
-\begin{itemize}
+described in section \fullref{coarse}):
+\begin{multicols}{3}\begin{itemize}
        \item \code{boostrapping}
        \item \code{cli}
        \item \code{database}
@@ -262,8 +263,7 @@ described in section TODO):
        \item \code{settings}
        \item \code{specification}
        \item \code{test}
-\end{itemize}
-TODO: two columns
+\end{itemize}\end{multicols}
 
 Each package is documented in the source code also, particularly in a file
 \file{package-info.java} residing in the respective package directory.