Minor change
authorPhilipp Martis <philipp2100@web.de>
Thu, 5 May 2016 13:04:58 +0000 (15:04 +0200)
committerPhilipp Martis <martispp@hspc01.informatik.uni-stuttgart.de>
Fri, 6 May 2016 13:54:54 +0000 (15:54 +0200)
Change not involving restructuring

However, on the subsubsection level there were slight changes.
Title page, package options and other subsidiary matters changed.

Bachelor thesis.pdf
Bachelor thesis.tex
OSL-Specification.pdf
OSL-Specification.tex
cs-cover/README.md [new file with mode: 0644]
cs-cover/uni-stuttgart-cs-cover.sty [new file with mode: 0644]
program.tex
program_arch.tex
program_code.tex
program_functionality.tex
program_interface.tex

index f0bb8f3..cbaa64b 100644 (file)
Binary files a/Bachelor thesis.pdf and b/Bachelor thesis.pdf differ
index cf83e7a..658fe89 100644 (file)
 
 % Documentclass etc.
 \documentclass[\myfontsize,a4paper,twoside=semi]{scrreprt}
+%\documentclass[paper=a4,twoside,bibliography=totoc,cleardoublepage=empty,parskip=half,final]{scrbook}  % Remember to comment in \backmatter!
 \usepackage[utf8]{inputenc}
 \usepackage[T1]{fontenc}
 \usepackage{lmodern}
 \usepackage{color}
+%\usepackage[hyperref,dvipsnames]{xcolor}
 
 % Einstellungen bez. des 'scrreprt'-Stils
 % Caption Schriftstil und -Groesse
 % Text
 \usepackage{textcomp}
 
-% Bilder
+% Bilder / Graphiken
 \usepackage[rflt]{floatflt}
 \usepackage{epsfig,wrapfig}
 \usepackage{subcaption}
 \usepackage{float}
+\usepackage{graphicx}
 
-% Mathematische Symbole
+% Mathematische Symbole etc.
 \usepackage{amsmath,amssymb}
+\usepackage[binary-units=true,decimalsymbol=comma]{siunitx}
+
+% Algorithmen
+\usepackage{algpseudocode}
+\usepackage{algorithm}
+\usepackage{algorithmicx}
 
 % Tabellen
 \usepackage{longtable,lscape}
 \lehead{\headmark}
 \rohead{\headmark}
 \pagestyle{scrheadings}
+%\usepackage[automark]{scrpage2}
+%\renewcommand{\footnoterule}{}
+%\addtolength{\skip\footins}{\baselineskip}
+%\usepackage{fnpos}
 
 % Listenerscheinung
 \setlength{\itemsep}{0ex}
 \setlength{\parskip}{2mm}
 
 % Biblatex
-\usepackage[style=alphabetic,maxnames=10,backref=true,backend=bibtex]{biblatex}
+\usepackage[style=alphabetic,maxnames=10,backref=true,block=space,backend=bibtex]{biblatex}
+\setlength{\bibitemsep}{1em}
 \bibliography{bibliography}
 
-% Hyperref
-\usepackage[]{hyperref}
+% Cover
+\usepackage[title={\mytitle{}},
+            author={Philipp Martis},
+            type=bachelor,
+            institute=ipvs,
+            number=TODO,
+            course=cs,
+            examiner={PD\ Dr.\ Holger Schwarz},
+            supervisor={M. Sc. Leif Harald Karlsen},
+            startdate={23rd of November 2015},
+            enddate={24th of May 2016},
+            crk={D.0},
+            language=english]{cs-cover/uni-stuttgart-cs-cover}
+
+% Appendix
+\usepackage{appendix}
+
+% Links
+%\usepackage{url}
+\usepackage{caption}  % Always link to the top of a figure or table
+\usepackage[]{hyperref}  % Should be loaded last!
 \hypersetup{
        unicode,
        pdftitle={\mytitle{}},
        bookmarksopen=true,
        bookmarksopenlevel=1
 }
-\usepackage{caption}  % Always link to the top of a figure or table
 
 
 \begin{document}
 \pagenumbering{roman}
 
 % Title page
-\KOMAoption{fontsize}{\smallerfontsize{}}
-\title{\mytitle{}}
-
-\author{Bachelor thesis \\
-       by \\
-       stud.\ inf.\ Philipp Martis}
-
-\publishers{realized at the \\
-       Institute for Parallel and Distributed Systems, \\
-       University of Stuttgart \\[5ex]
-       Stuttgart, in May 2016}
-
-\date{}
-\maketitle
-\KOMAoption{fontsize}{\myfontsize{}}
+\Titelblatt
+%\KOMAoption{fontsize}{\smallerfontsize{}}
+%\title{\mytitle{}}
+%\author{Bachelor thesis \\
+%      by \\
+%      stud.\ inf.\ Philipp Martis}
+%\publishers{realized at the \\
+%      Institute for Parallel and Distributed Systems, \\
+%      University of Stuttgart \\[5ex]
+%      Stuttgart, in May 2016}
+%\date{}
+%\maketitle
+%\KOMAoption{fontsize}{\myfontsize{}}
 
 % Abstract
 \include{abstract}
 \listoftables
 \addcontentsline{toc}{chapter}{List of tables}
 
+% List of algorithms
+%\listofalgorithms
+%\addcontentsline{toc}{chapter}{List of algorithms}
+
 \clearpage
 \pagestyle{plain}
 \renewcommand{\chaptermark}[1]{\markboth{#1}{}}
 % Summary
 \include{summary}
 
+%\backmatter  % Only for the book document classes
+
 % Appendix
 \include{appendix}
 \addcontentsline{toc}{chapter}{Appendix}
 \printbibliography
 \addcontentsline{toc}{chapter}{Bibliography}
 
+% Legal statement
+\pagestyle{empty}
+\renewcommand*{\chapterpagestyle}{empty}
+\clearpage
+\Versicherung
+
 \end{document}
index f7fa11d..dd18b6d 100644 (file)
Binary files a/OSL-Specification.pdf and b/OSL-Specification.pdf differ
index d6f105c..9f8519c 100644 (file)
 
 % Documentclass etc.
 \documentclass[\myfontsize,a4paper,twoside=semi]{scrreprt}
+%\documentclass[paper=a4,twoside,bibliography=totoc,cleardoublepage=empty,parskip=half,final]{scrbook}  % Remember to comment in \backmatter!
 \usepackage[utf8]{inputenc}
 \usepackage[T1]{fontenc}
 \usepackage{lmodern}
 \usepackage{color}
+%\usepackage[hyperref,dvipsnames]{xcolor}
 
 % Einstellungen bez. des 'scrreprt'-Stils
 % Caption Schriftstil und -Groesse
 % Text
 \usepackage{textcomp}
 
-% Bilder
+% Bilder / Graphiken
 \usepackage[rflt]{floatflt}
 \usepackage{epsfig,wrapfig}
 \usepackage{subcaption}
 \usepackage{float}
+\usepackage{graphicx}
 
-% Mathematische Symbole
+% Mathematische Symbole etc.
 \usepackage{amsmath,amssymb}
+\usepackage[binary-units=true,decimalsymbol=comma]{siunitx}
+
+% Algorithmen
+\usepackage{algpseudocode}
+\usepackage{algorithm}
+\usepackage{algorithmicx}
 
 % Tabellen
 \usepackage{longtable,lscape}
 \lehead{\headmark}
 \rohead{\headmark}
 \pagestyle{scrheadings}
+%\usepackage[automark]{scrpage2}
+%\renewcommand{\footnoterule}{}
+%\addtolength{\skip\footins}{\baselineskip}
+%\usepackage{fnpos}
 
 % Listenerscheinung
 \setlength{\itemsep}{0ex}
 \setlength{\parskip}{2mm}
 
 % Biblatex
-\usepackage[style=alphabetic,maxnames=10,backref=true,backend=bibtex]{biblatex}
+\usepackage[style=alphabetic,maxnames=10,backref=true,block=space,backend=bibtex]{biblatex}
+\setlength{\bibitemsep}{1em}
 \bibliography{bibliography}
 
-% Hyperref
-\usepackage[]{hyperref}
+%% Appendix
+%\usepackage{appendix}
+
+% Links
+%\usepackage{url}
+\usepackage{caption}  % Always link to the top of a figure or table
+\usepackage[]{hyperref}  % Should be loaded last!
 \hypersetup{
        unicode,
        pdftitle={\mytitle{}},
        bookmarksopen=true,
        bookmarksopenlevel=1
 }
-\usepackage{caption}  % Always link to the top of a figure or table
 
 
 \begin{document}
 % Title page
 \KOMAoption{fontsize}{\smallerfontsize{}}
 \title{\mytitle{}}
-
 \author{}
-
 \publishers{
        Logic and Intelligent Data, \\
        Department of Informatics, \\
        University of Oslo \\[5ex]}
-
 \date{}
 \maketitle
 \KOMAoption{fontsize}{\myfontsize{}}
 \listoftables
 \addcontentsline{toc}{chapter}{List of tables}
 
+% List of algorithms
+%\listofalgorithms
+%\addcontentsline{toc}{chapter}{List of algorithms}
+
 \clearpage
 \pagestyle{plain}
 \renewcommand{\chaptermark}[1]{\markboth{#1}{}}
 %% Summary
 %\include{summary}
 
+%\backmatter  % Only for the book document classes
+
 %% Appendix
 %\include{appendix}
 %\addcontentsline{toc}{chapter}{Appendix}
diff --git a/cs-cover/README.md b/cs-cover/README.md
new file mode 100644 (file)
index 0000000..0722bf2
--- /dev/null
@@ -0,0 +1,119 @@
+# About
+
+Unofficial LaTeX package for the required **cover page** for work at the University of Stuttgart, Computer Science.
+
+This package is a replacement for the old diplomtitel.sty
+
+## Features
+
+- utf8 
+- options for all required text on the coverpage
+
+## Installation
+
+- Download `uni-stuttgart-cs-cover.sty` or 
+- Clone this repository with `git clone https://github.com/latextemplates/uni-stuttgart-cs-cover.git` or
+- Use it as git submodule via `git submodule add https://github.com/latextemplates/uni-stuttgart-cs-cover.git uni-stuttgart-cs-cover`
+
+## Usage Example
+
+An example can be found in [thesis.tex](thesis.tex).
+
+## Usage 
+
+Just include the package with all options specified:
+
+    \usepackage[
+    title={Super relevant evaluation of new blackhole-generation method},
+    author={Max Musterjunge},
+    type=bachelor,
+    institute=iaas,
+    number=12345,
+    course=cs,
+       examiner={Prof.\ Dr.\ Hans Mustermann},
+       supervisor={Otto Normalverbraucher, M.Sc.},
+       startdate={2012/06/01},
+       enddate={2012/12/01},
+       crk={A.1, A.2},
+       language=english
+       ]{uni-stuttgart-cs-cover}
+
+Afterwards you can create the cover using `\Coverpage` and get the affirmation text by using `\Affirmation`
+
+## Supported Options
+
+This package supports the following options:
+
+- language: Language used for all labels and text.
+       - `language=german` will use german (default)
+       - `language=english` will use english
+
+- title: Title of work. Should be placed in curly braces:
+
+       - `title={My thesis title}`
+       - `title={My very long thesis title}`
+
+- author: Author of work. Should be placed in curly braces. May contain more than one author seperated by commas:
+       - `author={Peter Lustig}`
+       - `author={Peter Lustig, Franz Josef, Vladimir Sixth}`
+
+- type: Type of work. May be set to one of the following values or arbitrary text in curly braces:
+       - `type=bachelor` will label your work as Bachelor's Thesis
+       - `type=master` will label your work as Masters's Thesis
+       - `type=diplom` will label your work as Diploma Thesis
+       - `type=study` will label your work as Student Research Project
+       - `type=projectinf` will label your work as Projekt-INF
+       - `type={research project}` will label your work as research project
+       
+- institute: States for which institute you are doing this work. May be set to one of the following values or arbitrary text in curly braces:
+       - `institute=iaas` will state Institute of Architecture of Application Systems
+       - `institute=ipvs` will state Institute of Parallel and Distributed Systems
+       - `institute=fmi` will state Institute of Formal Methods in Computer Science
+       - `institute=iste` will state Institute of Software Technology
+       - `institute=iti` will state Institute of Computer Architecture and Computer Engineering
+       - `institute=iris` will state Institute of Computer-aided Product Development Systems
+       - `institute=vis` will state Institute of Visualization and Interactive Systems
+       - `institute=visus` will state Visualisation Research Center Stuttgart
+       - `institute=fac` will state Faculty of Computer Science
+       - `institute={Custom fictional institute}` will state Custom fictional institute
+
+- number: Running number of work. May contain arbitrary text. Should contain the number you got for your work.
+       - `number=1234` will label your work to have number 1234
+
+- course: Type of study. May be set to one of the following values or arbitrary text in curly braces:
+       - `course=cs` will state that your course of study is Computer Science
+       - `course=se` will state that your course of study is Software Engineering
+       - `course=mcl` will state that your course of study is Master Computational Linguistics
+       - `course=msv` will state that your course of study is Maschinelle Sprachverarbeitung
+       - `course=bis` will state that your course of study is Business Information Systems
+       - `course=simtech` will state that your course of study is Simulation Technology
+       - `course={New Study course}` will state that your course of study is New Study course
+
+- examiner: Your examiner. 
+       - `examiner={Prof.\ Dr.\ Hans Mustermann}`
+
+- supervisor: Your supervisor.
+       - `supervisor={Otto Normalverbraucher, M.Sc.}`
+
+- startdate: Startdate of your work.
+       - `startdate={2012/06/01}`
+
+- enddate: Enddate of your work.       
+       - `enddate={2012/12/01}`
+
+- crk: CR-Classification codes of your work. May be seperated by commas:
+       - `crk={A.1, A.2}`
+
+## Additional Optional Options
+
+- `setPageNumberToOne=true` will set the page after the cover to `1` (default false)
+- `setCoverPageNumberToMinusOne=true` will set `-1` as the page number for the cover page (default false)
+
+## Known Problems
+
+Multiline/Commands in option values are currently only supported if you load `kvoptions-patch` **before** the documentclass defintion like this:
+
+       \RequirePackage{kvoptions-patch}
+       \documentclass[twoside]{article}
+
+
diff --git a/cs-cover/uni-stuttgart-cs-cover.sty b/cs-cover/uni-stuttgart-cs-cover.sty
new file mode 100644 (file)
index 0000000..9b0db2f
--- /dev/null
@@ -0,0 +1,376 @@
+% (C) 1990-1996 Bernd Raichle
+% (C) 2001 Timo Heiber, Matthias Papesch
+% (C) 2005 Steffen Keul
+% (C) 2006 Nils Radtke, Oliver Kopp
+% (C) 2007 Oliver Kopp
+% (C) 2012 Oliver Kopp, Kai Mindermann, Niklas Schnelle
+
+\NeedsTeXFormat{LaTeX2e}
+\newcommand{\USCCover@Pgkname}{uni-stuttgart-cs-cover}
+\ProvidesPackage{\USCCover@Pgkname}[2012/11/20 Cover and affirmation for work at the University of Stuttgart, Computer Science.]
+\typeout{Package: `\USCCover@Pgkname' v3.0}
+% ------------------------------
+% required packages
+% ------------------------------
+% kvoptions for key value options support
+\RequirePackage{kvoptions}
+\RequirePackage{ifthen}
+
+% this package requires utf8 inputenc
+\def\USCCover@stop{\PackageWarningNoLine{\USCCover@Pgkname}
+  {This package won't work without loading\MessageBreak
+   `inputenc' or `inputenx' with the `utf8' option}%
+  \let\USCCover@Pgkname\@gobbletwo\endinput}
+\@ifpackageloaded{inputenx}
+  {\def\USCCover@tempa{inputenx}}
+  {\@ifpackageloaded{inputenc}{\def\USCCover@tempa{inputenc}}{\USCCover@stop}}
+\@ifpackagewith{\USCCover@tempa}{utf8}{}{\USCCover@stop}
+\@ifpackagewith{\USCCover@tempa}{utf8x}{\USCCover@stop}{}
+
+% ------------------------------
+% options
+% ------------------------------
+\SetupKeyvalOptions{
+       family=MCS,
+       prefix=MCS@
+}
+
+% for possible option values see README.md
+\DeclareStringOption[title not set]{title} % Title of the work
+\DeclareStringOption[author not set]{author}
+\DeclareStringOption[bachelor]{type}
+\DeclareStringOption[fac]{institute}
+\DeclareStringOption[not set]{number} % running number
+\DeclareStringOption[cs]{course}
+\DeclareStringOption[examiner not set]{examiner}
+\DeclareStringOption[supervisor not set]{supervisor} 
+\DeclareStringOption[startdate not set]{startdate} 
+\DeclareStringOption[enddate not set]{enddate}
+\DeclareStringOption[crk not set]{crk}
+
+\DeclareStringOption[german]{language}
+\DeclareBoolOption[false]{setPageNumberToOne}
+\DeclareBoolOption[false]{setCoverPageNumberToMinusOne}
+
+% ------------------------------
+% process options
+% ------------------------------
+\ProcessKeyvalOptions*
+
+% ------------------------------
+% define language specific labels:
+% ------------------------------
+% - labels are defined seperate for each language
+% - if language is not set, german is used
+% ------------------------------
+\def\labelsenglish{
+       \gdef\@labelExaminer{Examiner}%
+       %\gdef\@labelprueferin{Examiner}%
+       \gdef\@labelSupvervisor{Supervisor}%
+       %\gdef\@labelbetreuerin{Supervisor}%
+       \gdef\@labelCourse{Course of Study}%
+       \gdef\@labelStartdate{Commenced}%
+       \gdef\@labelEnddate{Completed}%
+       \gdef\@labelcrk{CR-Classification}%
+       \gdef\@labelUniversity{~\newline University of Stuttgart}%
+       \gdef\@labelDept{Faculty of Computer Science}%
+       
+       \gdef\@labelTypeStudy{Studienarbeit}%
+       \gdef\@labelTypeDiplom{Diplomarbeit}%
+       \gdef\@labelTypeBachelor{Bachelorarbeit}%
+       \gdef\@labelTypeMaster{Masterarbeit}%
+       \gdef\@labelTypeProjectINF{Projekt-INF}%
+       \gdef\@labelTypeFachstudie{Fachstudie}%
+       \gdef\@labelTypeProzessanalyse{Prozessanalyse}%
+       
+       \gdef\@labelCourseCS{Informatik}%
+       \gdef\@labelCourseSE{Softwaretechnik}%
+       \gdef\@labelCourseMCL{Computerlinguistik}%
+       \gdef\@labelCourseTK{Technische Kybernetik}%
+       \gdef\@labelCourseMSV{Maschinelle Sprachverarbeitung}%
+       \gdef\@labelCourseBIS{Wirtschaftsinformatik}%
+       \gdef\@labelCourseSimTech{Simulation Technology}%
+       
+       % institute names
+       \gdef\@labeliaas{Institute of Architecture of Application Systems}%
+       \gdef\@labelipvs{Institute of Parallel and Distributed Systems}%
+       \gdef\@labelfmi{Institute of Formal Methods in Computer Science}%
+       \gdef\@labeliste{Institute of Software Technology}%
+       \gdef\@labeliti{Institute of Computer Architecture and Computer Engineering}%
+       \gdef\@labeliris{Institute of Computer-aided Product Development Systems}%
+       \gdef\@labelvis{Institute for Visualization and Interactive Systems}%
+       
+       \gdef\@labelAffirmation{Declaration}%
+       \gdef\@AffirmationText{I hereby declare that the work presented in this thesis is entirely my own and that
+               I did not use any other sources and references than the listed ones.
+               I have marked all direct or indirect statements from other sources contained therein as quotations.
+               Neither this work nor significant parts of it were part of another examination procedure.
+               I have not published this work in whole or in part before.
+               The electronic copy is consistent with all submitted copies.
+       }
+       \gdef\@labelSignature{\ place, date, signature}
+}
+
+\def\labelsgerman{
+       \gdef\@labelExaminer{Prüfer/in}%
+       \gdef\@labelSupvervisor{Betreuer/in}%
+       \gdef\@labelCourse{Studiengang}%
+       \gdef\@labelStartdate{Beginn am}%
+       \gdef\@labelEnddate{Beendet am}%
+       \gdef\@labelcrk{CR-Nummer}%
+       \gdef\@labelUniversity{~\newline Universität Stuttgart}%
+       \gdef\@labelDept{Fakultät Informatik, Elektrotechnik und Informationstechnik}%
+       
+       \gdef\@labelTypeStudy{Studienarbeit}%
+       \gdef\@labelTypeDiplom{Diplomarbeit}%
+       \gdef\@labelTypeBachelor{Bachelorarbeit}%
+       \gdef\@labelTypeMaster{Masterarbeit}%
+       \gdef\@labelTypeProjectINF{Projekt-INF}%
+       \gdef\@labelTypeFachstudie{Fachstudie}%
+       \gdef\@labelTypeProzessanalyse{Prozessanalyse}%
+       
+       \gdef\@labelCourseCS{Informatik}%
+       \gdef\@labelCourseSE{Softwaretechnik}%
+       \gdef\@labelCourseMCL{Computerlinguistik}%
+       \gdef\@labelCourseTK{Technische Kybernetik}%
+       \gdef\@labelCourseMSV{Maschinelle Sprachverarbeitung}%
+       \gdef\@labelCourseBIS{Wirtschaftsinformatik}%
+       \gdef\@labelCourseSimTech{Simulation Technology}%
+       
+       % institute names
+       \gdef\@labeliaas{Institut für Architektur von Anwendungssystemen}%
+       \gdef\@labelipvs{Institut für Parallele und Verteilte Systeme}%
+       \gdef\@labelfmi{Institut für Formale Methoden der Informatik}%
+       \gdef\@labeliste{Institut für Softwaretechnologie}%
+       \gdef\@labeliti{Institut für Technische Informatik}%
+       \gdef\@labeliris{Institut für Rechnergestützte Ingenieursysteme}%
+       \gdef\@labelvis{Institut für Visualisierung und Interaktive Systeme}%
+       
+       \gdef\@labelAffirmation{Erklärung}%
+       \gdef\@AffirmationText{Ich versichere, diese Arbeit selbstständig verfasst zu haben.
+       Ich habe keine anderen als die angegebenen Quellen benutzt und alle wörtlich oder sinngemäß aus anderen Werken übernommene Aussagen als solche gekennzeichnet.
+       Weder diese Arbeit noch wesentliche Teile daraus waren bisher Gegenstand eines anderen Prüfungsverfahrens.
+       Ich habe diese Arbeit bisher weder teilweise noch vollständig veröffentlicht.
+       Das elektronische Exemplar stimmt mit allen eingereichten Exemplaren überein.
+       }
+       \gdef\@labelSignature{\ Ort, Datum, Unterschrift}
+}
+
+% set those labels according to the set language
+\newcommand{\USCCover@setLanguage{
+       \def\0{english}
+       \ifx\MCS@language\0
+               \labelsenglish
+       \else
+               \labelsgerman
+       \fi
+}}
+
+% set \@labelType if matched
+\newcommand{\USCCover@setType}{
+       \gdef\@labelType{\MCS@type}
+       \def\1{\MCS@type}
+       % dont remove last two braces / empty else clause
+       \def\0{diplom}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelType{\@labelTypeDiplom}}{}
+       \def\0{study}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelType{\@labelTypeStudy}}{}
+       \def\0{bachelor}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelType{\@labelTypeBachelor}}{}
+       \def\0{master}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelType{\@labelTypeMaster}}{}
+       \def\0{projectinf}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelType{\@labelTypeProjectINF}}{}
+}
+
+% ------------------------------               
+% Institute addresses
+% ------------------------------
+
+% general university address
+\gdef\@labelAddress{\@labelUniversity\\Universitätsstraße 38\\D--70569 Stuttgart}
+
+\newcommand{\USCCover@setInstitute}{
+       % use specified text if institute does not match
+       \gdef\@labelInstitute{\MCS@institute}
+       
+       \def\1{\MCS@institute}
+       % dont remove last two braces / empty else clause
+       \def\0{ipvs}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelInstitute{\@labelipvs\\\@labelAddress}}{}
+       \def\0{iaas}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelInstitute{\@labeliaas\\\@labelAddress}}{}
+       \def\0{fmi}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelInstitute{\@labelfmi\\\@labelAddress}}{}
+       \def\0{iste}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelInstitute{\@labeliste\\\@labelAddress}}{}
+       \def\0{iti}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelInstitute{\@labeliti\\\@labelUniversity\\Pfaffenwaldring 47\\D--70569 Stuttgart}}{}
+       \def\0{iris}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelInstitute{\@labeliris\\\@labelAddress}}{}
+       \def\0{vis}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelInstitute{\@labelvis\\\@labelAddress}}{}
+       \def\0{fac}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelInstitute{\@labelDept\\\@labelAddress}}{}
+}
+
+% ------------------------------               
+% Evaluate course option and set course
+% ------------------------------
+\newcommand{\USCCover@setCourse}{
+       % use specified text if course does not match
+       \gdef\@labelCourseValue{\MCS@course}
+       
+       \def\1{\MCS@course}
+       % dont remove last two braces / empty else clause
+       \def\0{cs}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelCourseValue{\@labelCourseCS}}{}
+       \def\0{se}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelCourseValue{\@labelCourseSE}}{}
+       \def\0{mcl}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelCourseValue{\@labelCourseMCL}}{}
+       \def\0{msv}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelCourseValue{\@labelCourseMSV}}{}
+       \def\0{bis}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelCourseValue{\@labelCourseBIS}}{}
+       \def\0{simtech}\ifthenelse{\equal{\0}{\1}}{\gdef\@labelCourseValue{\@labelCourseSimTech}}{}
+}
+
+% ------------------------------
+% evaluate options by calling those functions that set text accordingly
+% ------------------------------
+\USCCover@setLanguage
+\USCCover@setType
+\USCCover@setInstitute
+\USCCover@setCourse
+% ------------------------------               
+% helping commands
+% ------------------------------
+% - \USCCover@umrandet
+% - \USCCover@TBlabel
+% - \USCCover@TBlist
+% ------------------------------
+\def\USCCover@umrandet{\global\let\@USCCover@umrandet=\fbox}
+\let\@USCCover@umrandet\relax
+
+\newcommand{\USCCover@TBlabel}[1]{\textbf{#1}\hfil}
+
+\newenvironment{USCCover@TBlist}{%
+  \list{}{\labelwidth 45mm \leftmargin 70mm % alt: 35/60 mm
+          \rightmargin 20mm \let\makelabel\USCCover@TBlabel}%
+}{\endlist}
+
+% ------------------------------
+% usable commands
+% ------------------------------
+% - \Titelblatt
+% - \Versicherung
+% (contain code from old diplomtitel.sty)
+% ------------------------------
+\newcommand{\Titelblatt}{%
+  \cleardoublepage
+  \ifthenelse{\boolean{MCS@setCoverPageNumberToMinusOne}}{\setcounter{page}{-1}}{}
+\begingroup
+       \newcommand{\USCCover@isTwoColumn}{false}
+       \if@twocolumn \renewcommand{\USCCover@isTwoColumn}{true} \onecolumn \fi
+  \normalfont\sffamily
+  \pagestyle{empty}%
+  \thispagestyle{empty}%
+  %\fontfamily{ppl}\selectfont
+  %
+  \@normalsize \@setsize\normalsize{13.6pt}\xipt\@xipt
+  %
+  \frenchspacing    % besser, da viele Abk. (<- da ist schon eine)
+  \parskip=0pt\parindent=0pt\null
+  %
+  % Damit alles richtig funktioniert, mu"s der Ursprung auf die
+  %  tats"achliche linke obere Ecke des Blattes gelegt werden (ohne den
+  %  bekannten 1in Offset also).
+  %  Ausserdem werden die beiden Seitenr"ander auf 28mm + 4.5mm Falz
+  %  gesetzt, die Seitenh"ohe auf DIN A4-H"ohe.
+  %
+  \hsize=154mm       %% DIN A4: 210mm - 2*28mm
+  \columnwidth=\hsize \linewidth=\hsize
+  %
+  \dimen0=0pt
+  \advance\dimen0-\oddsidemargin
+  \advance\dimen0 2.6mm %% 
+  \advance\dimen0 4.5mm %% 
+ \hbox to 0pt{\kern\dimen0\vbox to\topskip{%
+  \dimen0=-1in
+  \advance\dimen0-\topmargin
+  \advance\dimen0-\headheight
+  \advance\dimen0-\headsep
+  \vskip\dimen0\relax
+  %
+
+  \vskip 20mm\relax %%%
+
+  \vbox to 70mm{
+  \begin{center}%
+    \@labelInstitute
+  \end{center}
+  \vfill}%
+
+  \vskip -4mm\relax
+  %%%%% ==> 155mm (Titel: 165mm/Autor: 195mm) von oben
+  %%% Die Box kann max. 100mm breit und 60mmm hoch sein,
+  %%% au"serdem wird noch ein Rand von mind. 2.5mm gelassen
+  \centerline{\fboxsep=0pt
+    \@USCCover@umrandet{\hbox to 100mm{\hfil
+    \vbox to 60mm{\hsize=95mm\parindent=0pt
+      \vskip 10mm plus 30mm minus 7.5mm
+      \begin{center}\@setsize\large{14pt}\xiipt\@xiipt %%\large
+        \@labelType\ Nr.\,\MCS@number
+      \end{center}%
+      \vskip 12.5mm plus 12.5mm minus 10mm
+      \begin{center}\@setsize\LARGE{22pt}\xviipt\@xviipt %%\LARGE
+        \textbf{ \MCS@title}
+      \end{center}%
+      \vskip 10mm plus 10mm minus 7.5mm
+      \begin{center}\@setsize\large{14pt}\xiipt\@xiipt %%\large
+        \MCS@author
+      \end{center}%
+      \vskip 17.5mm plus 35mm minus 12.5mm}\hfil}}}%
+  \vskip 20mm %%%%%
+
+  \vbox to 15mm{%
+    \begin{USCCover@TBlist}%
+      \item[\@labelCourse: ]\@labelCourseValue
+    \end{USCCover@TBlist}%
+    \vfill}%
+  \vbox to 45mm{%
+    \begin{USCCover@TBlist}%
+      \item[\@labelExaminer:]\MCS@examiner
+      \item[\@labelSupvervisor:]\MCS@supervisor
+    \end{USCCover@TBlist}%
+    \vfill}%
+  \vbox to 70mm{%%%%% ==> 85 mm von oben
+    \begin{USCCover@TBlist}%
+      \item[\@labelStartdate:]\MCS@startdate
+      \item[\@labelEnddate:]\MCS@enddate
+      \ifx\@crk\relax \else
+          \vskip 1.5\baselineskip
+          \item[\@labelcrk:]\MCS@crk
+      \fi
+    \end{USCCover@TBlist}%
+    \vfill}%
+
+ \vss}\hss}%
+  %
+  \thispagestyle{empty}%
+  \cleardoublepage % if twoside add a blank page after cover
+  % set counter to start at 1 after the clear(double)page
+  \ifthenelse{\boolean{MCS@setPageNumberToOne}}{\setcounter{page}{1}}{}
+  \newcommand{\USCCover@true}{true}
+  \ifthenelse{\equal{\USCCover@isTwoColumn}{\USCCover@true}}{\twocolumn}{}
+\endgroup
+}
+\newcommand{\Coverpage}{\Titelblatt}
+
+\newcommand{\Versicherung}{
+  \newcommand{\USCCover@isTwoColumn}{false}
+  \if@twocolumn \renewcommand{\USCCover@isTwoColumn}{true} \onecolumn \fi
+  \null
+  \vskip 5cm\relax
+       \begin{center}
+               \begin{minipage}[t]{10cm}
+                       \hbox{\normalfont\bfseries \@labelAffirmation}%
+                       \vskip 1cm\relax
+                       %\begin{flushleft}%
+                       \@AffirmationText
+                       %\end{flushleft}%
+                       \vskip 4cm\relax
+                       \hrulefill
+                       \vskip .4\baselineskip
+                       \hbox{\@labelSignature}
+               \end{minipage}
+       \end{center}
+  \clearpage
+  \newcommand{\USCCover@true}{true}
+  \ifthenelse{\equal{\USCCover@isTwoColumn}{\USCCover@true}}{\twocolumn}{}
+}
+\newcommand{\Affirmation}{\Versicherung}
index c66350f..2ddb521 100644 (file)
@@ -15,6 +15,8 @@ on the code level to yield clean code.
 Section \fullref{stats} mentions some figures about the program.
 Section \fullref{versioning} gives a brief timewise TODO overview over the program
 development and describes important milestones.
+For detailed descriptions of the classes and packages of \myprog{}, refer to
+Appendices TODO.
 
 Except the last section, this chapters' sections present the information in a
 functionally-structured fashion: the concepts and decisions are described along with
index 245e751..a351b2b 100644 (file)
@@ -6,7 +6,7 @@
 TODO: overall description, modularity, extendability, ex: easy to add new in-/output formats
 TODO: mapping profiles (maybe better in next subsection)
 
-\subsubsection{Package partitioning}
+\subsubsection{Package structuring}
 The $45$ classes of \myprog{} were assigned to $11$ packages, each containing
 classes responsible for the same area of operation or taking over similar roles.
 Care was taken that package division happened senseful, producing meaningful packages
@@ -19,6 +19,7 @@ implementation detail, this is further explained in section \fullref{code_packag
 The packages are introduced and described in table \ref{arch_tbl_packages}.
 The lists of classes each package contains are given in table \ref{arch_tbl_classes}
 in the next section \fullref{fine}.
+For a detailed package description, refer to Appendix TODO.
 
 \begin{table}[H]
        \begin{tabular}{p{3cm}|p{13cm}} %\KOMAoption{fontsize}{\smallerfontsize{}}
@@ -53,6 +54,33 @@ which carries information needed by other packages
 For this, it is required for \code{Main} not to reside in the \code{default}
 package \cite{java}.
 
+Decoupling some of the functionality of a package into a new package -- which,
+in a nesting package structure, most probably would have become a sub-package -- and
+thus sacrificing the benefit of having fewer packages also played a role in some cases.
+Namely, \code{osl} is a package on its own instead of being part of the
+\code{specification} package, the \code{bootstrapping} classes also form a package
+on their own instead of belonging to the \code{specification} package,
+the classes of the \code{log} and the \code{cli} packages were not merged into
+one package, although logging currently exclusively happens on the command line,
+and the functionality of the \code{test} package, though containing only a few
+lines of code, was separated into its own package.
+
+Even though the package structure would have become quite simpler with these changes
+applied -- $4$ out of $11$ packages could have been saved this way --
+the first aim mentioned -- meaningfulness and intuitiveness -- was taken seriously
+and the presented partitioning was considered a more natural and
+comprehensible structuring, emphasizing different roles and thus being a more proper
+foundation for future extensions of the program.
+For example, because the \code{bootstrapping} package is central to the program and
+takes over TODO an active, processing role and in that is completely different
+from the classes of the \code{specification} package which on their part have a
+\emph{representing} role, it was considered senseful not to merge these two packages.
+This undergirds the separation of concerns within the program and stresses that
+the functionality of the \code{bootstrapping} package should not interweave with
+that in the \code{specification} package, making it easier for both to stay
+independent and further develop into understandable and suitable units.
+
+
 \subsubsection{Package interaction}
 As mentioned, the structuring of the packages was driven by the aim to gain a notable
 amount of decoupling.
@@ -75,22 +103,41 @@ The current dependency structure, factoring in this restriction, is shown in fig
                \label{arch_fig_packages}
 \end{center}\end{figure}
 
-Though there are quite a number of dependencies (to be precise: $19$), many of them
-($8$, thus, nearly half) trace back to one central package in the middle,
-\code{settings}.
-This may seem odd at first glance, considering that most of the edges of the node
-representing package \code{settings} are outgoing edges and only one is incoming,
+Except for the package \code{settings} (which is further explained below),
+every package has at most two outgoing edges, that is packages it depends on.
+Previous versions of \myprog{} had a quite more complicated package dependency structure,
+depicted in figure \ref{arch_fig_packages_earlier}.
+In this previous package structure, the maximum number of dependencies of
+packages other than \code{settings} on other packages is three, which also seems
+reasonably less.
+However, in the new structuring, \code{specification} has no packages it depends on
+and thus suits its purpose of providing a mundane and straight-forward
+representation of an OBDA Specification much better.
+%Furthermore, \code{output} doesn't depend on \code{database} anymore.
+
+\begin{figure}[H]\begin{center}
+               \includegraphics[scale=0.86]{Images/package_graph_earlier.pdf}
+               \caption[Package dependencies in earlier versions of \myprog{}]{Package dependencies
+                       in earlier versions of \myprog{}. ``$\rightarrow$'' again means ``depends on''.}
+               \label{arch_fig_packages_earlier}
+\end{center}\end{figure}
+
+Though there still are quite a number of dependencies (to be precise: $19$),
+many of them ($8$, thus, nearly half) trace back to one central package
+in the middle, \code{settings}.
+This may seem odd at first glance, considering that most of the edges connecting to
+the \code{settings} node are outgoing edges and only one is incoming,
 whereas in a design where the settings are configured from within a single package
 and accessed from many other packages this would be the other way round.
 The reason for this constellation is that, as described in section \fullref{interface},
 all settings in \myprog{} are configured per bootstrapping job
 (there are no global settings) and so \code{settings}
-contains a class \code{Job} (and currently no other classes).
-\code{Job} represents the configuration of a bootstrapping job but also
+contains a class \code{Job} (and currently no other classes),
+which represents the configuration of a bootstrapping job but also
 provides a \code{perform()} method combining the facilities offered by the other
 packages.
 
-This way, the \code{perform()} method of the \code{Job} class acts as the central
+By this means, the \code{perform()} method of the \code{Job} class acts as the central
 driver performing the bootstrapping process, reducing the \code{main()} method two
 only $7$ lines of code and turning \code{settings} into something like an externalized
 part of the \code{main} package.
@@ -99,33 +146,26 @@ configuration files are introduced, \code{settings} will still be the central pa
 leaving the package structure and dependencies unchanged,
 since it either way contains information used by many other packages.
 This was the reason why it was not renamed to, for example, \code{driver}, which was
-considered, since it seems quite a bit unnatural to have the driver class reside in
-a package called ``settings'' at first glance.
-
-Previous versions of \myprog{} had a quite more complicated package dependency structure,
-depicted in figure \ref{arch_fig_packages_earlier}.
-
-\begin{figure}[H]\begin{center}
-               \includegraphics[scale=0.86]{Images/package_graph_earlier.pdf}
-               \caption[Package dependencies in earlier versions of \myprog{}]{Package dependencies
-                       in earlier versions of \myprog{}. ``$\rightarrow$'' again means ``depends on''.}
-               \label{arch_fig_packages_earlier}
-\end{center}\end{figure}
+considered, since at first glance it seems quite a bit unnatural
+to have the driver class reside in a package called ``settings''.
 
 %Package \code{helpers} depends on package \code{database}, which provides the \code{static}
 %method \code{getSQLTypeName}.
 
 \subsection{Fine structuring}
 \label{fine}
-\subsubsection{Package contents}
-\label{package_details}
 While the packages in \myprog{} are introduced and described in section \fullref{coarse},
 the classes that comprise them are addressed in this section.
+For a detailed class index, refer to Appendix TODO.
+TODO: total classes etc.
+
+\subsubsection{Package contents}
+\label{package_details}
 
 Table \ref{arch_tbl_classes} lists the classes each package contains.
 The packages \code{cli}, \code{main}, \code{osl} and \code{settings} contain only
 one class each, while the by far most extensive package is \code{database},
-containing $17$ classes.
+containing $15$ classes.
 
 \begin{table}[H]
        \begin{multicols}{2}\begin{itemize} %\KOMAoption{fontsize}{\smallerfontsize{}}
@@ -146,7 +186,6 @@ containing $17$ classes.
                                \item \code{DatabaseException}
                                \item \code{DBSchema}
                                \item \code{ForeignKey}
-                               \item \code{Helpers}
                                \item \code{Key}
                                \item \code{PrimaryKey}
                                \item \code{ReadableColumn}
@@ -155,16 +194,17 @@ containing $17$ classes.
                                \item \code{ReadableKey}
                                \item \code{ReadablePrimaryKey}
                                \item \code{RetrieveDBSchema}
-                               \item \code{SQLType}
                                \item \code{Table}
                                \item \code{TableSchema}
                        \end{itemize}
                        \item \code{helpers}
                        \begin{itemize}
+                               \item \code{Helpers}
                                \item \code{MapValueIterable}
                                \item \code{MapValueIterator}
                                \item \code{ReadOnlyIterable}
                                \item \code{ReadOnlyIterator}
+                               \item \code{SQLType}
                                \item \code{UserAbortException}
                        \end{itemize}
                        \newpage
@@ -220,8 +260,8 @@ roles, behave in an intuitive way, ideally representing artifacts from the world
 modeled in the program directly \cite{str3}, is a prerequisite to make the code
 clear and comprehensible on the architectural level.
 
-Section \fullref{code_classes} describes the identification and naming scheme for
-the classes in \myprog{}.
+Section \fullref{code_classes} as part of section \fullref{code}
+describes the identification and naming scheme for the classes in \myprog{}.
 However, it is also important, to arrange these classes in useful, comprehensible
 class hierarchies to avoid code duplication, make appropriate use of the type system,
 ease the design of precise and flexible interfaces and enhance the
@@ -229,6 +269,9 @@ adaptability and extensibility of the program.
 Figure \ref{arch_fig_hierachies} shows the class hierarchies in \myprog{},
 while standalone classes are listed in table \ref{arch_tbl_lone_classes}.
 
+\stepcounter{figure}
+\newcounter{figureNumberOfClassHierarchyFigure}
+\setcounter{figureNumberOfClassHierarchyFigure}{\value{figure}}
 \begin{figure}[H]\begin{center}
                \ContinuedFloat*
                \includegraphics[scale=0.86]{Images/inherit_graph_8.pdf}
@@ -278,7 +321,7 @@ while standalone classes are listed in table \ref{arch_tbl_lone_classes}.
 \begin{figure}[H]\begin{center}
                \ContinuedFloat*
                \includegraphics[scale=0.86]{Images/inherit_graph_4.pdf}
-               \setcounter{figure}{2} %TODO: variable
+               \setcounter{figure}{\value{figureNumberOfClassHierarchyFigure}}
                \caption[Class hierarchies in \myprog{}]{Class hierarchies in \myprog{}.
                        Interface names are italicized,
                        external classes or interfaces are hemmed with a gray frame.}
@@ -288,10 +331,10 @@ while standalone classes are listed in table \ref{arch_tbl_lone_classes}.
 \begin{table}[H]\begin{center}
                \begin{tabular}{l}
                        \itm{} \code{main.Main}\\
-                       \itm{} \code{database.Helpers}\\
                        \itm{} \code{database.RetrieveDBSchema}\\
-                       \itm{} \code{database.SQLType}\\
                        \itm{} \code{database.Table}\\
+                       \itm{} \code{helpers.Helpers}\\
+                       \itm{} \code{helpers.SQLType}\\
                        \itm{} \code{specification.OBDASpecification}\\
                        \itm{} \code{osl.OSLSpecification}\\
                        \itm{} \code{bootstrapping.Bootstrapping}\\
@@ -313,8 +356,8 @@ but the approach described by Stroustrup \cite{str4} to provide a rich set of
 so called ``concrete types'' not designed for use within class hierarchies, which
 ``build the foundation of every well-designed program \cite{str4}'' TODO.
 The details of this consideration are explained in section \fullref{code_interfaces}.
-In fact, many useful types were already offered by the \name{Java} API,
-so they were not re-implemented.
+In fact, many useful types were already offered by the \name{Java} API
+and of course were not re-implemented.
 
 Class \code{Column} with its interface \code{ReadableColumn} is an exception TODO
 in that it was given an interface although it is basically a concrete type.
@@ -324,7 +367,7 @@ This technique forced class \code{Column} to
 \code{implement} an interface, thus needlessly making it part of a class hierarchy,
 but also complicated the structure of some class hierarchies.
 Consider the class hierarchy around \code{ColumnSet},
-shown in the first graph TODO of figure \ref{arch_fig_hierachies}.
+shown in the \hyperref[first_hierarchy]{first graph} of figure \ref{arch_fig_hierachies}.
 Definitely, it seems overly complicated at the first glance.
 But this complexity solely is introduced by the artificial
 \code{Readable...} interfaces;
@@ -337,9 +380,14 @@ this hierarchy would be as simple as in the following graph:
                \label{arch_fig_colset_hierarchy_simplified}
 \end{center}\end{figure}
 
-However, TODO: still good
-
-TODO: rest self-explanatory
+However, since const correctness is an important mechanism effectively preventing
+errors while on the other hand introducing clarity by itself, it was considered
+too important to be sacrificed, even for a cleaner and more intuitive class hierarchy.
+The fact that the \code{Readable...} scheme is very straight-forward and a programmer
+reading the documentation knows about its purpose and the real, much smaller,
+complexity also makes some amends for the simplicity sacrificed.
+The const correctness mechanism itself thereby hinders uninformed or ignorant
+programmers from mistakenly using the wrong class in an interface in many cases.
 
 For more information about the program structure on the class level,
-see section \fullref{code}.
+see section \fullref{code}, while for a detailed class index refer to Appendix TODO.
index 6c83ce8..a514bbe 100644 (file)
@@ -7,90 +7,149 @@ 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.
+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()}
@@ -125,7 +184,7 @@ 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: summary
 
 \subsection{Classes}
 \label{code_classes}
@@ -145,9 +204,8 @@ As a consequence, the code declares classes like \code{Column}, \code{ColumnSet}
 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.
@@ -164,6 +222,7 @@ into class hierarchies.
 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}.
@@ -276,9 +335,13 @@ described in section \fullref{coarse}):
        \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}).
index e4680a0..439e192 100644 (file)
@@ -3,9 +3,11 @@
 As described in the introduction, the \myprog{} software basically is a program which
 automatically derives an OBDA specification from a relational database schema,
 which then can be used by other tools to drive the actual bootstrapping process.
-Its functionality is described in the next section
-(while leaving out self-evident features) and is then listed completely
+Its functionality is described in the next section,
+leaving out self-evident features, and is then listed completely
 in the section after that.
+The bootstrapping process as the core functionality of the software is described in
+section \fullref{bootstrapping}.
 
 \subsection{Description}
 The database schema is retrieved by connecting to an \name{SQL} database
index 3180b00..8fc194e 100644 (file)
@@ -128,14 +128,14 @@ Thus, a parameter defined for one operation (like the password
 in the example) will have no effect on other operations.
 This ensures that typical errors are prevented when merging several invocations
 of \myprog{} into one (or vice versa)
-and allows for a straight-forward, comprehensive and clean implementation.
+and allows for a straight-forward and comprehensive implementation.
 
 \subsubsection{Advanced modifications}
 Since \osl{} specifications are plain text files, a user can edit them in any desired
 text editor if he wants to change them in ways that go beyond the functionality
 \myprog{} provides or that can be achieved by scripts or programs modifying their
 input automatically.
-Because of \osl{} being defined to be a subset of \name{OWL} (see the specification
+Because of \osl{} being a subset of \name{OWL} (see the specification
 of \osl{} in section \ref{oslspec}), he can thereby take advantage of editors
 supporting syntax highlighting or other features making the handling of
 the respective \name{OWL} serialization more comfortable.
@@ -145,8 +145,8 @@ specification automatically or manually.
 Doing so, care has to be taken to make the ontology remain a conforming \osl{}
 specification. However, since the restrictions imposed by \osl{} are rather
 small and intuitive, this is easily achieved.
-Furthermore, upcoming tools supporting \osl{} (see section \fullref{future}) are very
-likely to be able to check their input for conformity with the \osl{} definition.
+Furthermore, upcoming tools supporting \osl{} (see section \fullref{future}) most
+likely will be able to check input files for conformity with the \osl{} definition.
 
 \subsection{Integration into systems}
 Besides the use cases described in section ``\nameref{basic}'',
@@ -155,7 +155,7 @@ For example, a database can be periodically checked for changes that make a
 re-bootstrapping necessary:
 \codepar{db2osl -d mydb myserver.org | sha256sum >oldsum\\
        cp oldsum newsum\\
-       while diff oldsum newsum; do\\
+       while diff oldsum newsum; do\ \ \# while checksums are the same\\
        \ind sleep 3600\ \ \# wait 1 hour\\
        \ind db2osl -d mydb myserver.org | sha256sum >newsum\\
        done\\