Programmierwerkzeuge-06-Dokumentation

TeX document icon Programmierwerkzeuge-06-Dokumentation.tex — TeX document, 10 KB (10495 bytes)

File contents

\documentclass[12pt, twoside]{scrartcl}
%Anfang OERMacros.tex
% Zum Erstellen mit pdfLaTeX wird diese Datei und der CC BY Button by.png im selben Verzeichnis benötigt. 
% by.png ist unter https://mirrors.creativecommons.org/presskit/buttons/88x31/png/by.png zu finden. 

% Für den Lizenzhinweis zur Nutzung dieser OER kann das Macro \OERLizenzHinweis verendet werden. 

\usepackage[utf8]{inputenc}
\def\Autor {Reinhard Brocks}
\def\HomeAutor {https://www.htwsaar.de/ingwi/fakultaet/personen/profile/Reinhard\%20Brocks}
\def\OERLizenzHinweis 
{
	\includegraphics{by} % by.png ist unter https://mirrors.creativecommons.org/presskit/buttons/88x31/png/by.png zu finden. 
	\begin{minipage}[b]{11cm}\footnotesize
		\href{\HomeAutor/oer/pwz/programmierwerkzeuge-06-dokumentation/at_download/file}{Programmierwerkzeuge - \mysubtitle} 
		von 
		\href{\HomeAutor}{\Autor} 
		ist lizenziert unter einer 
		\href{http://creativecommons.org/licenses/by/4.0/}{Creative Commons Namensnennung 4.0 International Lizenz}.
	\end{minipage}
}


\def\HinweisLatex {Für die Nutzung und die Bearbeitung steht das Dokument \href{\HomeAutor/oer/pwz/latex}{hier} 
	auch im \LaTeX-Format zur Verfügung.}

\def\MailAutor {reinhard.brocks@htwsaar.de}

\def\MiniKontakt 
{
	Fragen und Verbesserungsvorschläge bitte an Prof.~Dr.~\Autor, 
	Hochschule für Technik und Wirtschaft des Saarlandes. \\
	E-Mail: \href{mailto:\MailAutor}{\MailAutor}\\[2ex]
}

\def\Kontakt
{
	\MiniKontakt
	Einen Überblick über die Unterrichtseinheiten zu \glqq Programmierwerkzeuge\grqq{} 
	findet man \href{\HomeAutor/oer/pwz/programmierwerkzeuge-00-unterrichtskonzept/at_download/file}{hier}.\\[1ex]
}

\def\Disclaimer 
{
	\begin{footnotesize}
		\textbf{Disclaimer}: Der Autor übernimmt keine Haftung für eventuelle 
		Datenschutz- und sonstige Rechtsverletzungen in anderen Webangeboten, 
		auf die er einen Link gesetzt hat. Für die Inhalte der von ihm 
		verlinkten Fremdangebote sind die jeweiligen Herausgeber verantwortlich. 
		Vor dem Einrichten von Links sind die Webseiten der anderen Anbieter 
		mit großer Sorgfalt und nach bestem Wissen und Gewissen geprüft worden. 
		Es kann jedoch keine Gewähr für die Vollständigkeit und Richtigkeit von 
		Informationen auf verlinkten Seiten übernommen werden. 
		Falls auf Seiten verweisen wird, deren Inhalt Anlass zur 
		Beanstandung gibt, bittet der Autor um eine Mitteilung 
		(\textit{\href{mailto:\MailAutor}{\MailAutor}}).
	\end{footnotesize}
}
%Ende OERMacros.tex%
%Anfang PackagesMacros.tex
\usepackage{a4,german}
\usepackage{hyperref}
\usepackage{hyperxmp}
\usepackage{color}
\usepackage{graphics}
\usepackage{listings}
\lstset{language=Java}

\lstset{ frame=single, 
	numbers=left, numberstyle=\tiny, stepnumber=2, numbersep=5pt, 
	keywordstyle=\color{blue},
	commentstyle=\color{Definitionsfarbe},
	basicstyle=\footnotesize,
	stringstyle=\color{red}, identifierstyle=\color{black}\bfseries 
}

\parindent 0pt
\definecolor{Definitionsfarbe}{RGB}{0,100,0}
\newcommand{\TextBegriff}[1]{\textcolor{Definitionsfarbe}{\textbf{#1}}}


%Ende PackagesMacros.tex%

\def\mysubtitle {Unterrichtseinheit 6: Dokumentationswerkzeuge}
\def\mykeywords {Programmierwerkzeuge, Dokumentationswerkzeuge, JavaDoc, Doxygen}
\hypersetup
{
	pdftitle={Programmierwerkzeuge},
	pdfsubject={\mysubtitle},
	pdfauthor={Reinhard Brocks},
	pdfkeywords={\mykeywords},
	pdfcopyright={CC BY 4.0},
	pdflicenseurl={http://creativecommon.org/licenses/by/4.0/}
}

\title{\textbf{Programmierwerkzeuge}}
\subtitle{\mysubtitle \\[2ex]{\small Lehr- und Lernmaterialien}}
\author{}
\date{}

\begin{document}
\maketitle
\thispagestyle{empty}
\vfill

\begin{tabular}{|p{3cm}|p{10,5cm}|} \hline 
	Zielgruppe	&	Lernende, die schon eine Programmiersprache gelernt und 
					erste Erfahrungen in der Programmierung gesammelt haben.\\ \hline 
	Lernziele	&	Der Lernende weiß, was und wie man im Quellcode dokumentiert. 
					Er kennt das allgemeine Prinzip von Dokumentationsframeworks. 
					Er kann eine Dokumentation inklusive UML-Klassendiagrammen 
					aus Quellcode generieren. \\ \hline 
	Stichwörter & \mykeywords\\ \hline 
\end{tabular} \\[2ex]

\Kontakt

Versionsgeschichte\\[1ex]
\begin{tabular}{|l|l|l|}\hline 
	Datum 	& Änderung \\ \hline 
	26. Oktober 2019 & Erste Version \\ \hline 
\end{tabular}\\[1ex]

\OERLizenzHinweis\HinweisLatex
\newpage

\section*{Programmierwerkzeuge - Quellcodedokumentation}
\subsection*{Aufgabe: JavaDoc, UML-Klassendiagramm, 120 Minuten}
\begin{enumerate}
	\item Kommentieren Sie den Quelltext eines Projekts in der IDE Ihrer Wahl. 
	\item Generieren Sie eine Dokumentation aus dem Quellcode mit der IDE. 
	\item Generieren Sie über Kommandozeile eine Code-Dokumentation in einem 
			separaten Verzeichnis mit Namen \glqq doc\grqq. 
	\item Generieren Sie ein UML-Klassendiagramm und speichern Sie dieses in Form einer jpg-Datei ab. 
\end{enumerate}
Welche Einstellungen für die Generierung der Dokumentation gibt es? 

\subsection*{Aufgabe: Fragen und Aufgaben zur Reflexion, 30 Minuten}
\begin{enumerate}
	\item Was soll alles in einem Software-Projekt dokumentiert werden? Was kann davon im Code dokumentiert werden? Welche Java documentation tags gibt es? Was kann nicht im Code dokumentiert werden? 
	Erstellen Sie eine Mind-Map. 
	\item Warum sollte Software im Source-Code kommentiert werden? 
	\item Vergleichen Sie die Funktionsweise von JavaDoc (siehe \cite{JavaDoc}) mit der von Doxygen (siehe \cite{Doxygen}) oder TTCN-3 Doc (siehe \cite{TTCN-3}). 
			Nach welchem allgemeinen Prinzip funktioniert Code-Dokumentation? 
			(Stichwort: documentation tags, javadoc-Kommentar)
	\item Diskutieren Sie über die Aussage \glqq (Unit-)Tests sind die beste Quellcode-Dokumentation\grqq.
	\item Diskutieren Sie über die Aussage \glqq Dokumentation ist nervig. Der Code ist genug Dokumentation\grqq.
	\item Was sind Kommentare und was ist Dokumentation? 
	\item Welche Empfehlung zur Quellcodedokumentation kann man machen? 
\end{enumerate}


\newpage
\subsection*{Arbeitsergebnisse}
\textbf{Definition} \TextBegriff{Software-Dokumentationswerkzeug} (siehe auch \cite{DocWZ}): Das sind  
Werkzeuge, die aus Quellcode eine Dokumentation im HTML-Format generieren. Andere Formate sind teilweise 
auch möglich. Die Dokumentation bezieht sich auf die Schnittstellen und ist für Softwareentwickler gedacht, 
die mit dieser Schnittstelle arbeiten werden. Zum einen müssen dazu die Schnittstellen dokumentiert werden. 
Zum anderen können die Werkzeuge auch direkt auf Basis der Sourcen Informationen generieren. \\[1ex]

Das Grundprinzip der Dokumentationswerkzeuge ist einfach. Quellcode-Kommen\-tare, die für 
Dokumentationswerkzeuge gedacht sind, werden in mehrzeiligen Kommentaren (\lstinline{/* comment */}) 
geschrieben. Das Dokumentationswerkzeug erkennt üblicherweise an einem weiteren $\ast$, dass der 
Kommentar ein \TextBegriff{Dokumentationskommentar} ist. Also \lstinline{/** comment */}. 
Innerhalb des Dokumentationskommentars gibt es dann sogenannte \TextBegriff{Dokumentationstags}, 
an dem das Werkzeug erkennt, was dokumentiert wird. So einen Tag erkennt man üblicherweise an \lstinline{@<tag>}. 

Es ist von Vorteil, dass der Entwickler beim Programmieren direkt im Quellcode mit seinem Editor 
die Dokumentation für andere Entwickler erstellen kann. 

Neben der API-Dokumentation kann z.\,B. zusätzlich zu den Klassenabhängigkeiten auch eine 
graphische Klassenübersicht in Form eines UML-Diagramms generiert werden. Bei größeren 
Programmen könnte man sich auch eine graphische package-Übersicht mit den Abhängigkeiten vorstellen. 

Eine IDE sollte in irgendeiner Weise die Erzeugung von Dokumentationsblöcken 
unterstützen. Für Eclipse gibt es dazu z.\,B. das Plug-in JAutodoc (siehe \cite{JAutoDoc}). 
Statische Code-Analyse-Tools können überprüfen, ob z.\,B. alle public-Methoden oder alle 
Parameter einer Methode dokumentiert wurden. 

\subsection*{Hinweise für den Dozenten}
Die Lernenden kennen normalerweise schon JavaDoc. Neu ist, systematisch verschiedene Einstellungen 
zu entdecken und auszuprobieren. 

Als Lehrender wird man die Erfahrung machen, dass die Studenten ohne Erläuterungen schnell 
selbstständig ein UML-Klassendiagramm generieren können. Man sollte aufpassen, dass dann 
aber kein großes UML-Tool installiert wird, dessen Handhabung kompliziert ist. Das Lernziel 
ist auch erreicht, wenn der Lernende mit einem kleinen Tool sieht, wie aus dem Source-Code 
ein Klassendiagramm erzeugt wird. 

Die Generierung der Dokumentation in der Konsole ist im Allgemeinen neu und bereitet die 
meisten Schwierigkeiten. Vielen Lernenden war nicht bewusst, dass dazu ein JDK installiert 
sein muss. Probleme gab es auch, da das Prinzip der Umgebungsvariable \glqq PATH\grqq{} nicht 
bekannt war und in der Konsole \glqq JavaDoc\grqq{} nicht gefunden wurde. 

Eine Übersicht über JavaDoc findet man unter \cite{JavaDoc}. Insbesondere gibt es hier auch 
Empfehlungen zum Schreiben von Kommentaren. In dieser Unterrichtseinheit geht es allerdings 
um das Werkzeug an sich. Es geht nicht darum zu erläutern, was alles zu einer Projektdokumentation 
gehört oder wie man z.\,B. lesbaren oder selbstdokumentierenden Code schreibt oder wie verschiedene 
technische Dokumente (Anforderungsdokumentation, Architekturdokumentation) aufgebaut sind. 

\begin{thebibliography}{9}
\bibitem{JavaDoc}Oracle, Javadoc Tool Home: \glqq Javadoc Tool\grqq, URL: \url{https://www.oracle.com/technetwork/java/javase/documentation/javadoc-137458.html}(Abgerufen am 25.10.2019)
\bibitem{DocWZ}Seite \glqq Software-Dokumentationswerkzeug\grqq. In: Wikipedia, Die freie Enzyklopädie. Bearbeitungsstand: 9. September 2016, 08:56 UTC. URL: \url{https://de.wikipedia.org/w/index.php?title=Software-Dokumentationswerkzeug&oldid=157783842} (Abgerufen: 25. Oktober2019, 16:25 UTC)
\bibitem{TTCN-3}ETSI Standard ETSI ES 201 873-10 V4.5.1: \glqq Methods for Testing and Specification (MTS);
The Testing and Test Control Notation version 3;
Part 10: TTCN-3 Documentation Comment Specification\grqq, URL \url{https://www.etsi.org/deliver/etsi_es/201800_201899/20187310/04.05.01_60/es_20187310v040501p.pdf} (Abgerufen: 25.10.2019) (04/2013)
\bibitem{JAutoDoc}Martin Kesting: \glqq JAutoDoc - Eclispe Plugin\grqq{} URL: \url{http://jautodoc.sourceforge.net/} (Abgerufen am 25.10.2019)
\bibitem{Doxygen}Dimitri van Heesch: \glqq Doygen\grqq{}, URL: \url{http://www.doxygen.nl/} (Abgerufen am 25.10.2019)
\end{thebibliography}
\Disclaimer
\end{document}