"Als Entwickler verbringt man die meiste Zeit damit, den Code anderer Leute zu verstehen."

Eclipse Magazin: Wie senkt Intent die Hürde für eine gute und nützliche Dokumentation?

Alex Lagarde: Intent ist eine in die Eclipse IDE integrierte Dokumentationsumgebung. Sie ermöglicht es, die eigene Dokumentation direkt in Eclipse zu bearbeiten, ohne dass man zu einem anderen Tool wechseln müsste. Außerdem kann man für jeden Abschnitt der Dokumentation, egal, wie klein, einen eigenen Intent-Editor öffnen. Damit befolgt man das Mantra „Gehirn entlasten“, das allen Mylyn-Tools gemein ist: Wir zeigen dem User nur das, was für ihn in einer bestimmten Situation relevant ist, keine Hunderte von Seiten Dokumentation. Wie vorhin erklärt, gibt es da eine unbequeme Wahrheit über Dokumentation: Obwohl wir das Jahr 2012 schreiben, ist es noch immer langwierig und unangenehm, die Dokumentation auf dem neuesten Stand zu halten. Genau aus diesem Grund haben wir das Projekt Mylyn Intent ins Leben gerufen: um Tooling bereitzustellen, mit dem sich die Dokumentation mit jedem technischen Artefakt jederzeit synchronisieren lässt, ob Java-Code, Modelle, C++-Code, Plug-in-Abhängigkeiten, Beispielcode aus dem Internet etc.

Eclipse Magazin: Wie genau funktioniert dieses Tooling?

Alex Lagarde: Wir erhalten einfach die formalen Verbindungen zwischen jedem Teil der Dokumentation und dem Artefakt, auf das er sich bezieht, aufrecht. Wenn man also seinen Code verändert, wird Intent diese Links nutzen, um festzustellen, welche Teile der Dokumentation aktualisiert werden sollten. Dadurch vermeidet man mühseliges Nachschlagen. Intent platziert Fehlermarkierungen in allen veralteten Teilen der Dokumentation, die man sehen und mit einem Klick in der Eclipse Platform View öffnen kann. Dann kann man die Unterschiede zwischen den Spezifizierungen im Intent-Dokument und dem entsprechenden technischen Artefakt – z. B. „Die Klasse wurde umbenannt“ – grafisch visualisieren lassen. Und entscheiden, ob man die Dokumentation oder den Code aktualisiert.

Eclipse Magazin: Wann und wie erfolgen die Updates?

Alex Lagarde: Man kann die veraltete Dokumentation updaten, wann immer man möchte. Dazu sucht man sich einfach den für den eigenen Arbeitsprozess effizientesten Weg aus. Die Disciplined Agile Delivery [1] beschreibt mehrere Prozesse zum Aktualisieren von Dokumentation: Man kann sie z. B. sofort aktualisieren („kontinuierliches Dokumentieren“), man kann warten, bis der Code stabil ist (d. h. das jeweilige Problem gelöst ist), kurz vor einem Release aktualisieren („spätes Dokumentieren“) oder wenn es Beschwerden gibt („nur dokumentieren, wenn es gar nicht anders geht“).

Eclipse Magazin: Also ist Intent im Prinzip ein Synchronisations-Tool?

Alex Lagarde: Es ist mehr als das: Es schlägt eine Brücke zwischen technischen Artefakten und High-Level-Concerns. Es ist ein perfektes Medium, um Constraints der Software auf höherer Ebene zu definieren. Im Grunde hat man solche Constraints ja ohnehin immer schon definiert: Das Team hat schließlich dieselben Entwicklungsleitfäden, Prozesse und Good Practices. Aber meistens werden diese Constraints nicht formal festgehalten. Bestenfalls werden sie in natürlicher Sprache in einer Dokumentationsdatei aufgeschrieben. So ist es mühsam, den Code zu überprüfen, und man macht sich schnell unbeliebt, wenn man seinen Entwicklern erklären muss, dass sie nicht so coden, wie man es von ihnen erwartet. Da es außerdem keinen Beleg für die Constraints gibt, ist man nie sicher, ob man sie erfüllt.

Eclipse Magazin: Und was macht Intent in diesem Zusammenhang?

Alex Lagarde: Intent stellt Tooling für das automatische Überprüfen dieser Constraints und Leitlinien zur Verfügung. Man kann also z. B. in Intent eine Regel hinzufügen, die besagt, dass kein Bug geschlossen werden darf, bis der zugehörige Test geschrieben worden ist. Oder dass jedes Feature, das der Enduser angezeigt bekommt, innerhalb des User Guides mit einem Screenshot vorgeführt wird. Sobald gegen diese Regeln verstoßen wird, zeigt Intent in der Eclipse Problem View Validierungsprobleme an und hebt die Elemente hervor, die zum Regelverstoß geführt haben. Also weiß man als Entwickler noch vor dem Committen, dass man einige der Entwicklungsleitfäden nicht eingehalten hat, und kann sich sofort darum kümmern.

Kurz gesagt hilft Intent also dabei, eine Dokumentation zu schreiben, die immer auf dem neuesten Stand ist und prüft automatisch Constraints auf höherer Ebene. Die Dokumentation wird das Wissen eines Teams verlässlich bewahren. Man spart Zeit bei der gezielten Suche nach Informationen und beim Code-Review.

Eclipse Magazin: Intent ist ein Unterprojekt unter Mylyn Docs. Wie fügt es sich in die Task-Philosophie von Mylyn ein?

Alex Lagarde: Das Top-Level-Projekt Mylyn begreift sich selbst als Application-Lifecycle-Management-(ALM-)Framework für Eclipse. Jedes Mylyn-Projekt steuert Tooling für ALM-Anforderungen bei. Dokumentation ist ein wesentlicher Bestandteil von ALM. Deshalb wurde „Mylyn Docs“ mit Unterprojekten wie Wikitext oder Intent gegründet.

Intent unterstützt die obersten Ziele von ALM: Es erhöht die Produktivität, da das Team Best Practices für die Entwicklung miteinander teilen kann. Intent ermöglicht es auch, nur die Teile der Dokumentation zu berücksichtigen, die für die aktuelle Task relevant sind – dadurch, dass nur die wesentlichen Abschnitte der Dokumentation in den Kontext einer Mylyn-Task eingebettet werden. Dadurch ist es außerdem einfacher, auf Anforderungen, die den aktuell interessanten Code betreffen, zuzugreifen.

Wie außerdem schon erklärt, ermöglicht es Intent, Dokumentation und Ideen in Echtzeit zu teilen, und der Codewartungsaufwand wird durch die Synchronisation von Anwendung und Design reduziert.

Kommentare

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.