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.
+to yield clean, readable and extensible 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.
+wherever possible instead of just effacing the ambiguity with comments.
+This approach is further explained in section \fullref{speaking} and
+rendered many uses of comments unnecessary.
-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-\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.
+An exception from this was the highlighting of subdivisions.
In class and method implementations, comments like
\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
+were deliberately used to ease navigation inside source files,
+but also to enhance readability: 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, and thereby sticking strictly to the so-called
-``Composed Method Pattern'' \cite{composed}.
+Another alternative would have been to use separate methods for these code
+pieces, and thereby sticking strictly to the so-called
+``Composed Method Pattern'' \cite{composed},
+as was done in other cases.
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.
+Consequently, having longer methods at some places that are optically separated
+into smaller units that are in fact independent from each other was considered
+an elegant solution, although, surprisingly, this technique does not seem to be
+proposed that often in the literature.
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.
+This proved even more useful due to the fact that \name{Doxygen} supports all
+of the used \name{Javadoc} comments TODO (but not vice versa TODO).
-\subsection{Speaking code}
+\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:
-
+As mentioned in section \fullref{comments}, the code was tried to be designed to
+``speak for itself'' as much as possible instead of making its readers depend on
+comments that provide an understanding.
+In doing so, besides reducing code size due to the missing comments,
+clean code amenable to unfamiliar readers and unpredictable changes was enforced.
+This is especially important since, as described in section \fullref{arch},
+\myprog{} was designed to not only be a standalone program but also offer
+components suitable for reusability.
+%TODO: understandability <- code size
+
+The following topics were identified to be addressed to get what can be
+conceived as ``speaking code'':
\begin{itemize}
+ \item Meaningful typing
+ \item Method names
\item Variable names
- \item Control flow
+ \item Intuitive control flow
+ \item Limited nesting
+ \item Compact code units
+ \item Usage of well-known structures
\end{itemize}
+~\\The rest of this section describes these topics in some detail.
+Besides, an intuitive architecture and suitable, well-designed libraries
+also contribute to the clarity of the code.
+
+\subsubsection{Meaningful typing}
+Meaningful typing includes the direct mapping of entities of the modeled world
+to code entities \cite{str4} as well as an expressive naming scheme
+for the obtained types.
+Furthermore, inheritance should be used to express commonalities, to avoid
+code duplication and to separate implementations from interfaces \cite{str4}.
+
+All real-world artifacts to be modeled like database schemata, tables, table schemata.
+columns, keys and OBDA Specifications with their certain map types were directly
+translated into classes having simple predicting names like \code{Table},
+\code{TableSchema} and \code{Key}.
+Package affiliation provided the correct context to unambiguously understand these names.
+
+\subsubsection{Method names}
+Assigning expressive names to methods is a substantially important part of
+producing speaking code, since methods encapsulate operation and as such
+are important ``building blocks'' for other methods \cite{str4} and ultimately
+the whole program.
+Furthermore, method names often occur in interfaces and therefore are not limited
+to a local scope, and neither are easily changeable without affecting callers
+\cite{java}.
+
+Care was taken that method names reflect all important aspects of the respective
+method's behavior and
+
+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.
+
\subsubsection{Variable names}
-A very important part of speaking code
+To keep implementation code readable, care was taken to name variables
+meaningful yet concise. If this was not possible, expressiveness was preferred
+over conciseness.
+
+For example, in the implementation of the database schema retrieval,
+variables containing data directly obtained from querying the database
+and thus being subject to further processing was consequently prefixed
+with ``\code{recvd}'', although in most cases this technically would not have
+been necessary.
+
+\subsubsection{Intuitive control flow}
+
+\subsubsection{Limited nesting}
+
+\subsubsection{Compact code units}
+
+\subsubsection{Usage of well-known structures}
\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.
-
+potentially even unpracticed programmers, who besides have their emphasis
+on the concepts of bootstrapping rather than details of the present code anyway.
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 \cite{str4}.
-In modern programming languages, of course the main instruments for achieving
-this are the type system and exceptions.
+In modern object-oriented 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{str3}.
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
+enforcing the treatment of errors \cite{str4}, preventing the programmer from using
corrupted information in many cases.
-An example of both mechanism, static type information and exceptions, acting
+An example of both mechanisms, 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()}
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: summary
\subsection{Classes}
\label{code_classes}
As described in section \fullref{speaking}, class names were chosen to be concise
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{code_packages}, for the description
-of the packages themselves and their structuring, see section \fullref{coarse}).
+which is why the previously mentioned class names are unambiguous.
+For details about package use, see section \fullref{code_packages}.
Care was taken not to introduce unnecessary classes, thereby complicating
code structure and increasing the number of source files and program entities.
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.
+TODO: powerful, preventing errors, clarity
Unfortunately, \name{Java} lacks a keyword like \name{C++}'s \code{const},
making it harder to achieve const correctness \cite{final}.
\item \code{test}
\end{itemize}\end{multicols}
-Each package is documented in the source code also, particularly in a file
+For the description of the packages, their interaction and considerations on
+their structuring, see section \fullref{coarse}.
+For a detailed package description, refer to Appendix TODO.
+
+Each package is documented in the source code also, namely 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).
+as described in section \fullref{tools}).
git://git.uio.no / u / philim / db2osl_thesis.git / blobdiff