Software Engineering Build Management und Dokumentation

Transkript

1 Software Engineering Build Management und Dokumentation Prof. Adrian A. Müller, PMP, PSM 1, CSM Fachbereich Informatik und Mikrosystemtechnik 1

2 Wiederholung In Zeitpunkt einem Aktivität neu angelegten svn-repository t1 Datei "Anwendung.java" erstmalig hochgeladen (committed) werden t2 Datei zu "Test.java" den erstmalig im hochgeladen Folgenden (committed) genannten t3 Geänderte Datei "Anwendung.java" commited Zeitpunkten t4 Geänderte Datei die "Anwendung.java" folgenden commited Aktivitäten t5 Geänderte Datei "Test.java" commited ausgeführt: t6 Für den aktuellen Stand wird ein Tag "V1" erstellt t7 t8 t9 t10 t11 t12 Geänderte Datei "Test.java" commited Nun wird für Testzwecke ein Zweig "Z1" erstellt Im Zweig: Geänderte Datei "Test.java" commited Im Zweig: Geänderte Datei "Test.java" commited In der Hauptentwicklungslinie: Geänderte Datei "Anwendung.java" commited Im Zweig: Geänderte Datei "Anwendung.java" commited 2

3 Entscheidungen im Projekt Ordnerstruktur des Projekts Wo liegen die Quelltexte? Wo liegen die Binaries? Wohin kopiert man Ressourcen wie Konfigurationsdateien, Grafiken Wo liegen die Tests? Wo liegen Bibliotheken, wie benennt man sie? Wie geht man mit Abhängigkeiten (dependencies) um? Wie benennt man Klassen, Interfaces, Packages, usw.? Wie wird der Code dokumentiert? Wie wird Logging durchgeführt? Wie wird Persistenz umgesetzt? Nach: Schatten et al, Best Practice Software Engineering. Spektrum Akademischer Verlag

4 Hilfsmittel Konventionen Code-Konventionen Konventionen für Ordnerstrukturen, Dokumentation usw. Tools und Frameworks IDE (Entwicklungsumgebung, Integrated Development Environment) Syntax-Highlighting, Überprüfung mancher Konventionen, Code-Quality-Checks Z. B. Checkstyle, SourceMonitor Dokumentationstools Z. B. Java Doc Logging-Tools Z. B. java.util.logging, log4j Persistenzframeworks Z. B. Hibernate 4

5 Build-Management: Warum Automatisierung? Wiederkehrende Aufgaben in der Implementierung Kompilieren Post- und Preprocessing Dokumentation generieren Deployment auf Test-Server Tests ausführen Während der Entwicklung häufig zu wiederholen, z. T. täglich oder öfter Manuelle Durchführung Aufwändig Mögliche Fehlerquelle Nicht eindeutig reproduzierbar Nach: Schatten et al, Best Practice Software Engineering. Spektrum Akademischer Verlag

6 Automatisierung des Build-Prozesses Automatisierbare Schritte (Beispiele) Validierung von Sourcecode Code-Generierung (z. B. Konfigurationsdateien, Deployment-Deskriptor) Automatisierte Code-Quality-Checks Kompilieren Dependency-Management Verwaltung benötigter Bibliotheken (für die Kompilierung, zur Auslieferung) Post-Processing von Binaries (z. B. für Aspekt-orientierte Programmierung) Ausführen von Tests, Erstellen von Test-Reports Generieren von Dokumentation (z. B. Javadoc, Webseiten, ) Zusammenstellen der Software für die Auslieferung Verpacken der Software in Installationsdateien oder Archiven Hochladen auf einen Server Nach: Schatten et al, Best Practice Software Engineering. Spektrum Akademischer Verlag

7 Build-Tool Beispiel: Apache Ant Es gibt zahlreiche Build Tools, z. B. make hauptsächlich in der C/C++ -Entwicklung eingesetzt Ant und Maven für die Java-Entwicklung Ant ist die Abkürzung für Another Neat Tool Frei verfügbar, in Java geschrieben Verwendet XML-basierte Skripte Eingebaute Unterstützung für eine Reihe häufig benötigter Aufgaben Erweiterbar Eingebaute Tasks Java-Anwendungen kompilieren Javadoc-Dokumentationen generieren Archive erzeugen Dateien kopieren und Löschen etc. XML-Dateien validieren Sourcecode aus Versionsmanagement-Systemen auschecken JUnit-Tests durchführen 7

8 Ant Überblick Ant verwendet eine XML-Datei zur Konfiguration, normalerweise build.xml Ant builds enthalten: Task Tasks Targets Target Atomare Aufgabe, z. B. Kompilieren Zusammenfassung von Tasks Man kann Abhängigkeiten von anderen Targets definieren Ant kümmert sich darum, dass die Targets in der richtigen Reihenfolge ausgeführt werden 8

9 Ant: Nutzung Über die Kommandozeile In Eclipse integriert 9

10 Beispiel eines Ant-Skripts(1) Es soll ein Skript erstellt werden, das die folgenden Aufgaben durchführt: 1. Die Verzeichnisse build, docs, dist löschen 2. Die Verzeichnisse build, docs, dist neu anlegen 3. Den Java-Code kompilieren 4. Die Javadoc-Dokumentation generieren 5. Die Java-Klassen in eine ausführbare jar-datei packen 10

11 Beispiel eines Ant-Skripts(2) Anlegen einer build.xml-datei im Projekt-Verzeichnis: wird. Jedes Build-File hat genau ein Projekt Name des default-target, das ausgeführt wird, wenn ant ohne target-parameter aufgerufen Verzeichnis, auf das sich alle relativen Pfade beziehen. Properties entsprechen Variablen <?xml version="1.0"?> <project name="ant-test" default="main" basedir="."> <!-- Sets variables which can later be used. --> <!-- The value of a property is accessed via ${} --> <property name="src.dir" value="src" /> <property name="build.dir" value="build" /> <property name="dist.dir" value="dist" /> <property name="docs.dir" value="docs" /> Verwendung von Properties Tasks <!-- Deletes the existing build, docs and dist directory--> <target name="clean"> <delete dir="${build.dir}" /> <delete dir="${docs.dir}" /> <delete dir="${dist.dir}" /> </target> Targets <!-- Creates the build, docs and dist directory--> <target name="makedir"> <mkdir dir="${build.dir}" /> Beispiel von Lars Vogel: Apache Ant Tutorial, <mkdir dir="${docs.dir}" /> <mkdir dir="${dist.dir}" /> </target> (leicht modifiziert) 11

12 Beispiel eines Ant-Skripts(3) Abhängigkeiten: Das target compile ist von clean und makedir abhängig. Daher führt Ant automatisch zuerst diese beiden anderen Targets aus. Für komplexere Angaben zu einem Task gibt es eigene XML- Tags. <!-- Compiles the java code --> <target name="compile" depends="clean, makedir"> <javac srcdir="${src.dir}" destdir="${build.dir}"> </javac> </target> <!-- Creates Javadoc --> <target name="docs" depends="compile"> <javadoc packagenames="src" sourcepath="${src.dir}" destdir="${docs.dir}"> <!-- Define which files / directory should get included, we include all --> <fileset dir="${src.dir}"> <include name="**" /> </fileset> </javadoc> </target> <!--Creates the deployable jar file --> <target name="jar" depends="compile"> <jar destfile="${dist.dir}\ant-test.jar" basedir="${build.dir}"> <manifest> <attribute name="main-class" value="test.main" /> </manifest> </jar> </target> <target name="main" depends="compile, jar, docs"> <description>main target</description> </target> Abhängig vom target compile Das am Anfang als default angegebene target, das beim Ausführen von Ant automatisch durchgeführt wird. Aufgrund der Abhängigkeiten werden alle anderen definierten targets vorher ausgeführt. </project> Beispiel von Lars Vogel (siehe vorige Folie) 12

13 Ausführung Buildfile: C:\Workspace\Ant-Test\build.xml clean: [delete] Deleting directory C:\Workspace\Ant-Test\build [delete] Deleting directory C:\Workspace\Ant-Test\docs [delete] Deleting directory C:\Workspace\Ant-Test\dist makedir: [mkdir] Created dir: C:\Workspace\Ant-Test\build [mkdir] Created dir: C:\Workspace\Ant-Test\docs [mkdir] Created dir: C:\Workspace\Ant-Test\dist compile: [javac] Compiling 4 source files to C:\Workspace\Ant-Test\build [javac] Creating empty C:\Workspace\Ant-Test\build\math\package-info.class jar: [jar] Building jar: C:\Workspace\Ant-Test\dist\ant-test.jar docs: [javadoc] Generating Javadoc [javadoc] Javadoc execution [javadoc] Loading source file C:\Workspace\Ant-Test\src\math\MyMath.java... [javadoc] Loading source file C:\Workspace\Ant-Test\src\math\Sums.java... [javadoc] Loading source file C:\Workspace\Ant-Test\src\math\package-info.java... [javadoc] Loading source file C:\Workspace\Ant-Test\src\test\Main.java... [javadoc] Constructing Javadoc information... [javadoc] Standard Doclet version 1.6.0_30 [javadoc] Building tree for all the packages and classes... [javadoc] Building index for all the packages and classes... [javadoc] Building index for all classes... main: BUILD SUCCESSFUL Total time: 2 seconds 13

14 Häufig genutzte Tasks Dateisystem-Tasks mkdir, copy, move, delete, zip, unzip, tar, untar Java-Tasks javac, java, jar, javadoc Versionsmanagement-Systeme Testen cvs, perforce, Für Subversion gibt es eine Erweiterung: svnant junit, junitreport Ausführen externer Programme exec Weitere mail, ftp 14

15 Continuous Integration - Prinzipien Nur ein Sourcecode-Repository im Projekt, mit dem alle arbeiten Automatisierter Build Automatisierte Tests Jeder Entwickler sollte mindestens einmal täglich seine Änderungen in das Repository committen Der Build sollte schnell ablaufen, so dass häufige Builds möglich sind Z. B. nur geänderte Sourcen kompilieren Automatisiertes Deployment Der Build sollte wenigstens einmal täglich auf einem neutralen Rechner automatisiert ausgeführt werden Neutraler Rechner: Kein Entwicklungsrechner, entspricht dem Zielsystem Die Build- und Testergebnisse werden z. B. auf einer generierten Intranetseite dem gesamten Projekt zur Verfügung gestellt Nach: Schatten et al, Best Practice Software Engineering. Spektrum Akademischer Verlag 2010 und 16

16 Dokumentation mit Javadoc Nutzen Sie die Möglichkeiten von Dokumentationstools wie Javadoc Verwendung von Doc Comments im Quelltext /** * Hier steht der Kommentar, der * mehrere Zeilen überspannen kann. */ /** Einzeiliger Kommentar */ 17

17 Berücksichtigte Dateien Javadoc erstellt Dokumentationen aus Quellcodedateien Package-Beschreibungen Overview-Dateien ( overview.html ) Diverse weitere Dateien Erzeugt eine strukturierte HTML-Dokumentation, wie sie von der Java API-Dokumentation bekannt ist. 18

18 Quellcodedateien Doc Comments können vor Klassen Attributen Konstruktoren Methoden stehen Sie müssen aber direkt vor der jeweiligen Deklaration stehen 19

19 Dokumentation von packages In einer Datei package-info.java (oder package.html) Beispiel: Nutzung von HTML-Tags Inline-Tag Tag-Section mit Block Tags /** * Provides the classes necessary to create an * applet and the classes an applet uses * to communicate with its applet context. * <p> * The applet framework involves two entities: * the applet and the applet context. * An applet is an embeddable window (see the * {@link java.awt.panel} class) with a few extra * methods that the applet context can use to * initialize, start, and stop the applet. * 1.0 java.awt */ package java.lang.applet; Ein Doc Kommentar besteht aus einer Beschreibung gefolgt von einer Tag- Section. Beide sind optional, können aber nur einmal und nur in dieser Reihenfolge vorkommen. Der erste Satz der Beschreibung ist wichtig. Er erscheint in der Übersichtsdarstellung- Package-Deklaration Quelle: docs/technotes/tools/windows/javadoc.html 20

20 Dokumentation von Klassen /** * A class representing a window on the screen. * For example: * <pre> * Window win = new Window(parent); * win.show(); * </pre> * Sami Shaio 1.15, 13 Dec 2006 java.awt.basewindow java.awt.button */ class Window extends BaseWindow {... } Quelle: docs/technotes/tools/windows/javadoc.html 21

21 Dokumentation von Methoden Wichtig ist die Dokumentation von öffentlichen Methoden, die von anderen Entwicklern genutzt werden sollen. Sie sollten anhand der Beschreibung erkennen können, was man der Methode übergeben muss, was sie tut, und was sie zurückgibt. Für jeden Parameter: Name und Beschreibung Beschreibung der Rückgabe Welche Exceptions werden unter welchen Bedingungen geworfen? /** * Returns the character at the specified index. An index * ranges from <code>0</code> to <code>length() - 1</code>. * index the index of the desired character. the desired character. StringIndexOutOfRangeException * if the index is not in the range <code>0</code> * to <code>length()-1</code>. java.lang.character#charvalue() */ public char charat(int index) {... } Quelle: docs/technotes/tools/windows/javadoc.html 22

22 Dokumentation von Attributen /** * The X-coordinate of the component. * #getlocation() */ int x = ; Quelle: docs/technotes/tools/windows/javadoc.html 23

23 Javadoc Tags klassenname name klassenname versions-bezeichnung package.class#member label} Autor(en) Das Element ist veraltet und sollte nicht mehr benutzt werden Exception und unter welchen Bedingungen sie geworfen wird Parameter mit Name und Beschreibung der Bedeutung und erlaubter Werte Rückgabewert mit Beschreibung der Bedeutung und möglicher Werte Verweis. Mögliche Angaben: String, url, package.class#methode Seit dieser Version ist das Element in der Software enthalten Synonym zu exception Version der Software, zu der der Code gehört aber inline-link im Text 24

24 Javadoc-Unterstützung in Eclipse Automatisch generierte Kommentar- Gerüste /** allweyer * */ public class Sums { } /** n1 n2 */ public int add(int n1, int n2){ return n1 + n2; } Kommentar- Templates unter Preferences > Java > Code Style > Code Templates > Comments Erzeugen von Attribut- oder Methoden- Kommentar-Gerüsten über das Kontext- Menü Source > Generate Element Comment (Alt Shift-J) 25

25 Javadoc-Generierung in Eclipse 26

26 Javadoc Java API Dokumentation Selbst generiertes Javadoc 27

27 Wie kann man die Dokumentation automatisch erzeugen? <javadoc destdir="docs/api" author="true" version="true" use="true" windowtitle="test API"> <packageset dir="src" defaultexcludes="yes"> <include name="com/dummy/test/**"/> <exclude name="com/dummy/test/doc-files/**"/> </packageset> <doctitle><![cdata[<h1>test</h1>]]></doctitle> <bottom><![cdata[<i>copyright 2000 Dummy Corp. All Rights Reserved.</i>]]></bottom> <tag name="todo" scope="all" description="to do:"/> </javadoc> 28

28 Aufgabe Überlegen Sie fünf Aspekte, die schlechten Code ausmachen, d. h. Code der schlecht verständlich ist schlecht wartbar ist schlecht wiederverwendbar ist schlecht testbar ist fehleranfällig ist wenig performant ist 29

29 Hinweise zur Aufgabe Allgemein auf Code-Konventionen hinweisen Benennungen Verständlichkeit Englisch / Deutsch Einheitliche Benennungen, Einrückungen, Klammerung etc. Reihenfolgen Nutzung von Exceptions Kommentierung Strukturierung (kleine, übersichtliche Methoden, lose Kopplung etc.) Keine Duplizierung Maßnahmen Konventionen aufstellen Einhaltung überprüfen (Tools) Code Reviews / Pair Programming 30