[u/philim/db2osl_thesis.git] / program_code.tex

\section{Code style}
\label{code}
TODO: Conventions, ex.: iterators
As the final system hopefully will have a long living cycle TODO
and will be used and refined by many people, high code quality was an important aim.
Beyond architectural issues this also involves cleanness on the lower level,
like the design of classes and the implementation of methods.
Common software development principles were followed TODO and
the unfamiliar reader was constantly taken into account
to yield clean, usable and readable code.

\subsection{Comments}
\label{comments}
Comments were used at places ambiguities or misinterpretations could arise,
yet care was taken to face such problems at their roots and solve them
wherever possible instead of just eliminating the ambiguity with comments.

Consider the following method in \file{CLIDatabaseInteraction.java}:
\codepar{public static void promptAbortRetrieveDBSchemaAndWait\\
        \ind(final FutureTask<DBSchema> retriever) throws SQLException}

It could have been called \code{promptAbortRetrieveDBSchema} only, with the
waiting mentioned in a comment.
However, the waiting is such an important part of its behavior, that this
wouldn't have been enough, so the waiting was included in the function name.
Since the method is called at one place only, the lengthening of the method
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,
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}

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
plain comments, for example to specify parameters, return types, exceptions
and links to other parts of the documentation.

\subsection{Speaking code}
\label{speaking}
As mentioned in section \fullref{comments}, the use of ``speaking code'' as
introduced TODO
renders many uses of comments unnecessary.
In particular, the following aspects are commonly considered when referring to
the term ``speaking code'' TODO:

\begin{itemize}
        \item Variable names
        \item Control flow
\end{itemize}

\subsubsection{Variable names}
A very important part of speaking code 

\subsection{Robustness against incorrect use}
Care was taken to produce code that is robust to incorrect use, making it
suitable for the expected environment of sporadic updates by unfamiliar and
potentially even unpracticed programmers who very likely have their emphasis
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.

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}.
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
corrupted information in many cases.

An example of both mechanism, static type information and exceptions, acting
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
\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
\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,
was reliable.

They were then changed to return the 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
null check and tries to get a definite value from one of these methods
when the correct value currently is not known.

Comparing two unknown values -- thus, two null pointers --
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()}
instead of \code{col1.isUnique().booleanValue() == col2.isUnique().booleanValue()}.
\\TODO: Java rules.

TODO: more, summary

\subsection{Classes}
\label{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}.

\subsubsection{Identification of classes}
To identify potential classes, entities from the problem domain were -- if reasonable --
directly represented as 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
and effective.
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}).

Care was taken not to introduce unnecessary classes, thereby complicating
code structure and increasing the number of source files and program entities.
Especially artificial classes, having little or no reference to real-world
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.

\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,
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.
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,
it is not possible to declare methods that return read-only objects TODO --
placing a \code{final} before the method's return type would declare the
method \code{final}. Similarly, there is no way to express that a method must not change
the state of its object parameters. A method like \code{public f(final Object obj)}
is only liable to not assigning a new value to its parameter object \code{obj} \cite{java}
(which, if allowed, wouldn't affect the caller anyway \cite{java}).
Methods changing its state, however, are allowed to be called on \code{obj} without
restrictions \cite{java}.

Several possibilities were considered to address this problem:
\begin{itemize}
        \item Not implementing const correctness, but stating the access rules in
        comments only
        \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
        \item Deriving classes offering the modifying methods from the read-only
        classes
\end{itemize}

Not implementing const correctness at all of course would have been the simplest
possibility, producing the shortest and most readable code, but since
incautious manipulation of objects would possibly have introduced subtle,
hard-to-spot errors which in many cases would have occurred under additional
conditions only and at other places, for example when inserting a \code{Column}
into a \code{ColumnSet}, this method was not seriously considered.

Using intentionally angular, conspicuous names also was not considered seriously,
since it would have cluttered the code for the only sake of hopefully warning
programmers of possible errors -- and not attempting to avoid them technically.

So the introduction of new classes was considered the most effective and cleanest
solution, either in the form of ``editor'' classes or derived classes offering the
modifying methods directly. Again -- as in the identification of classes --,
the most direct solution was considered the best, so the latter form of introducing
additional classes was chosen and classes like \code{ReadableColumn},
\code{ReadableColumnSet} et cetera were introduced which offer only the read-only
functionality and usually occur in interfaces.
Their counterparts including modifying methods also were derived from them and the
implications of modifications were explained in their documentation, while the
issue and the approach as such were also mentioned in the documentation of the
\code{Readable...} classes.
The \code{Readable...} classes can be converted to their fully-functional
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},
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,
the interface is often given names like \code{ITableSchema}
or \code{TableSchemaInterface}.

However, for a special purpose program with a relatively fixed set of classes
mostly representing real-world artifacts from the problem domain,
this approach was considered overly cluttering, introducing artificial
code entities for no benefit.
In particular, as explained in section TODO, all program classes either are
standing alone TODO or belong to a class hierarchy derived from at least one
interface.
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
(an obvious choice, of course, for \code{ColumnSet}).
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
concise but nevertheless expressive.
This only was possible through the use of 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
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
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}
        \item \code{boostrapping}
        \item \code{cli}
        \item \code{database}
        \item \code{helpers}
        \item \code{log}
        \item \code{main}
        \item \code{osl}
        \item \code{output}
        \item \code{settings}
        \item \code{specification}
        \item \code{test}
\end{itemize}
TODO: two columns

Each package is documented in the source code also, particularly in a file
\file{package-info.java} residing in the respective package directory.
This is a common scheme supported by the \name{Eclipse} IDE as well as the
documentation generation systems \name{javadoc} and \name{doxygen} TODO
(all of which were used in the creation of the program,
as described in section TODO).