Documenting the Collaboration Aspect of a Software System in Source Code. Diploma Thesis

1. Fakultät Infortmatik Institut für SMT, Softwaretechnologie
Rule Based Documentation-
Documenting the Collaboration
Aspect of Software Systems
Dresden, 14.02.2006

2. Inhaltsübersicht
01 Einleitung
02 Konzept
03 Realisierung
04 Evaluierung
05 Demonstration
06 Ausblick
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 20

3. 01 Einleitung
Problemstellung
“Documentation is often poorly written. (Studie [1])
“
“Documentation is always outdated relative to the current
state of a software system. (2/3 Zustimmung in [1])
”
In der Maintenance Phase: „50% of a programmer’s time is
spent trying to understand existing code. [2]
“
“the maintenance phase accounts for over 60% of the
development time-line. [3]
“
“[..] no object is an island. All objects stand in relationship to
others, on whom they rely for services and control. [4] “
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 1 / 20
[1] Lethbridge,Singer,Forward [2] Kacofegits,Churcher [3] Vestdam [4] Beck,Cunningham

4. 01 Einleitung
Einordnung
Dokumentation
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 2 / 20

5. 01 Einleitung
Einordnung
Dokumentation
Eingebettet
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 2 / 20

6. 01 Einleitung
Einordnung
Dokumentation
Eingebettet
Dok
Prog
Dok
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 2 / 20

7. 01 Einleitung
Einordnung
Dokumentation
Eingebettet
Dok Prog
Prog Dok
Dok Prog
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 2 / 20

8. 01 Einleitung
Einordnung
Dokumentation
Eingebettet Separiert
Dok Prog
Prog Dok
Dok Prog
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 2 / 20

9. 01 Einleitung
Einordnung
Dokumentation
Eingebettet Separiert
Dok Prog
Prog Dok Prog Dok
Dok Prog
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 2 / 20

10. 01 Einleitung
Einordnung
Dokumentation
Eingebettet Separiert
Dok Prog
Prog Dok Prog Dok Prog Dok
Dok Prog
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 2 / 20

11. 01 Einleitung
Einordnung
Dokumentation
Eingebettet Separiert
Dok Prog
Prog
Dok
Dok
Prog
Prog Dok Prog Dok
?
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 2 / 20

12. 01 Einleitung
Einordnung
Dokumentation
Eingebettet Separiert
Dok Prog
Prog
Dok
Dok
Prog
Prog Dok Prog Dok
?
Prog Dok
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 2 / 20

13. 01 Einleitung
Problemstellung
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 3 / 20

14. 01 Einleitung
Problemstellung
Non-Cohesive Documentation
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 3 / 20

15. 01 Einleitung
Problemstellung
Non-Cohesive Documentation
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 3 / 20

16. 01 Einleitung
Problemstellung
Non-Cohesive Documentation
Tangled Documentation
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 3 / 20

17. 01 Einleitung
Problemstellung
Non-Cohesive Documentation
Tangled Documentation
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 3 / 20

18. 01 Einleitung
Problemstellung
Non-Cohesive Documentation
Tangled Documentation
Scattered Documentation
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 3 / 20

19. 01 Einleitung
Problemstellung
Non-Cohesive Documentation
Tangled Documentation
Scattered Documentation
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 3 / 20

20. 02 Konzept
Idee
Programmkonstrukte (Felder, Methoden ...) kontext-sensitiv
zu anderen Programmkonstrukten dokumentieren
-> Dokumentieren eines Collaboration Task im Quelltext
Mit „Role Models“ bereits ein erprobtes Instrument für die
Modellierung von „Object Collaborations“ vorhanden
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 4 / 20

21. 02 Konzept
Rollen Modelle
graphische Notation
textuelle Notation
}
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 5 / 20

22. 02 Konzept
Documentation Model
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 6 / 20

23. 02 Konzept
Konsequenzen
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 7 / 20

24. 02 Konzept
Konsequenzen
Kommentare unabhängig von Programm-Konstrukten
(vermeidet scattered Documentation)
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 7 / 20

25. 02 Konzept
Konsequenzen
Kommentare unabhängig von Programm-Konstrukten
(vermeidet scattered Documentation)
Kommentare für ein Programm-Konstrukt können sich
schichten / überlagern
(vermeidet tangled Documentation)
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 7 / 20

26. 02 Konzept
Konsequenzen
Kommentare unabhängig von Programm-Konstrukten
(vermeidet scattered Documentation)
Kommentare für ein Programm-Konstrukt können sich
schichten / überlagern
(vermeidet tangled Documentation)
Kommentare stehen zueinander in Beziehung
(vermeidet non-cohesive Documentation)
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 7 / 20

27. 02 Konzept
Relevanz-Sortierung
Da M-zu-N Beziehung zwischen Kommentar und Programm-
Konstrukt; mehrere Kommentare pro Kontext möglich.
Zu viel ungefilterte Dokumention eventuell nachteilig für
Entwickler
Vgl. Web-Suche: Nur erste Einträge werden gesondert beachtet
-> „Matching“ Dokumentationen nach Relevanz sortieren
(Relevanzbewertung notwendig)
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 8 / 20

28. 02 Konzept
Relevanz-Sortierung
Relevanz Heuristiken
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 9 / 20

29. 02 Konzept
Relevanz-Sortierung
Relevanz Heuristiken
Kontext-Unabhängig
Anzahl der
Muster Länge des Grad der
Instanzen Kommentars Spezifizierung
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 9 / 20

30. 02 Konzept
Relevanz-Sortierung
Relevanz Heuristiken
Kontext-Unabhängig Kontext-Abhängig
Anzahl der
Muster Länge des Grad der Hierach. Kontext
Instanzen Kommentars Spezifizierung Pfadlänge Spezifizierung
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 9 / 20

31. 03 Realisierung
Quellcode-Dokumentation Relation
Um Collaboration Task (nicht einzelne Collaboration) zu
dokumentieren - keine direkte Adressierung möglich
-> Formale Beschreibung (strukturell) des dokumentierten
Musters verbindet beide Konzepte miteinander
Selektion von Quelltext Element nicht auf Basis der Position
sondern Relation zu anderen Quelltext Elementen
‣ Pattern Role Annotation (Attribut Grammatiken)
‣ AspectJ / Pointcut Sprachen
‣ Graph basierte Ansätze
‣ Ontologie basierte Ansätze
‣ DataLog
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 10 / 20

32. 03 Realisierung
Domänen-Modell
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 11 / 20

33. 03 Realisierung
Dokumentationssprache
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 12 / 20

34. 03 Realisierung
Dokumentationssprache
Beispielinstanz SimpleExp[
class(?CA), method(?CA,?MA),
class(?CB), method(?CB,?MB),
calls(?MA,?MB,?), re_name(?CA,/Display$/) ]
{
CA:“Eine Klasse die auf Display endet“;
CM:“Eine Methode in %CA%“;
CB:“weite Klasse die in %CA% benutzt wird“;
MB:“Methode in %CB% wird von %MA%
aufgerufen“;
}
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 12 / 20

35. 03 Realisierung
Implementierung
Plug-In für Eclipse Platform
basiert auf JQuery Plug-In
Bestandteile:
‣ Kontext-Sensitiver „Documentation View“
‣ Dokumentationseingabe-Dialog
‣ Dokumentationsverwaltung-Dialog
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 13 / 20

36. 04 Evaluierung
Kandidaten
Testen des Konzeptes/Implementierung an 3 gewählten
Projekten:
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 14 / 20

37. 04 Evaluierung
Kandidaten
Testen des Konzeptes/Implementierung an 3 gewählten
Projekten:
‣ RuBaDoc: 3 kLoc , 49 C/I
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 14 / 20

38. 04 Evaluierung
Kandidaten
Testen des Konzeptes/Implementierung an 3 gewählten
Projekten:
‣ RuBaDoc: 3 kLoc , 49 C/I
‣ JHotDraw: 21 kLoc , 290 C/I
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 14 / 20

39. 04 Evaluierung
Kandidaten
Testen des Konzeptes/Implementierung an 3 gewählten
Projekten:
‣ RuBaDoc: 3 kLoc , 49 C/I
‣ JHotDraw: 21 kLoc , 290 C/I
‣ Tomcat 6: 155 kLoc , 1376 C/I
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 14 / 20

40. 04 Evaluierung
Kriterien
Unterschiedliche Collaboration Tasks:
‣ generelle Template Class Collaboration , viele
Vorkommen im Projekt
‣ Singleton Entwurfsmuster: strukturell gut beschreibar
‣ Visitor Entwurfsmuster: Namensmuster für Programm-
Konstrukte, komplexere Struktur als Singleton
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 15 / 20

41. 04 Evaluierung
Ergebnisse: Plug-In Initialisierung
Projekt LoC # FB Fakten FB Zeit Fakt/LoC Zeit/LoC
RuBaDoc 2988 5119 2876 ms 1,67 0.96 ms
JHotDraw 20522 42852 12893 ms 2,09 0,63 ms
Tomcat 6 155118 241664 152023 ms 1,56 0,98 ms
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 16 / 20

42. 04 Evaluierung
Ergebnisse: Plug-In Initialisierung
Projekt LoC # FB Fakten FB Zeit Fakt/LoC Zeit/LoC
RuBaDoc 2988 5119 2876 ms 1,67 0.96 ms
JHotDraw 20522 42852 12893 ms 2,09 0,63 ms
Tomcat 6 155118 241664 152023 ms 1,56 0,98 ms
#FB Fakten
FB Zeit
LoC
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 16 / 20

43. 04 Evaluierung
Ergebnisse: Bestimmung Code Fragmente f. Kommentare
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 17 / 20

44. 04 Evaluierung
Ergebnisse: Bestimmung Code Fragmente f. Kommentare
Projekt Dauer # Auftreten Dauer/kLoC
RuBaDoc 30 ms 9 10,207
JHotDraw 821 ms 195 40,000
Tomcat 6 3491 ms 1204 22,509
Template-Class Collaboration
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 17 / 20

45. 04 Evaluierung
Ergebnisse: Bestimmung Code Fragmente f. Kommentare
Projekt Dauer # Auftreten Dauer/kLoC
RuBaDoc 30 ms 9 10,207
JHotDraw 821 ms 195 40,000
Tomcat 6 3491 ms 1204 22,509
Template-Class Collaboration
Projekt Dauer # Auftreten Dauer/kLoC
RuBaDoc 5 ms 5 1,673
JHotDraw 18 ms 19 0,901
Tomcat 6 2022 ms 5 13,167
Singleton Collaboration
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 17 / 20

46. 04 Evaluierung
Ergebnisse: Bestimmung Code Fragmente f. Kommentare
Projekt Dauer # Auftreten Dauer/kLoC
RuBaDoc 30 ms 9 10,207
JHotDraw 821 ms 195 40,000
Tomcat 6 3491 ms 1204 22,509
Template-Class Collaboration
Projekt Dauer # Auftreten Dauer/kLoC
RuBaDoc 5 ms 5 1,673
JHotDraw 18 ms 19 0,901
Tomcat 6 2022 ms 5 13,167
Singleton Collaboration
Projekt Dauer # Auftreten Dauer/kLoC
RuBaDoc 7 ms 2 2,342
JHotDraw 43 ms 4 2,095
Tomcat 6 363 ms 5 2,340
Visitor Collaboration
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 17 / 20

47. 04 Evaluierung
Ergebnisse: Bestimmung Code Fragmente f. Kommentare
Ausführungszeit in ms
Template Class
Singleton
Visitor
LoC
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 18 / 20

48. 05 Demonstration
DEMO
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 19 / 20

49. 05 Ausblick
Mögliche zukünftige Arbeiten
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 20 / 20

50. 05 Ausblick
Mögliche zukünftige Arbeiten
‣ Einbindung verschiedener Source Code Reasoner
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 20 / 20

51. 05 Ausblick
Mögliche zukünftige Arbeiten
‣ Einbindung verschiedener Source Code Reasoner
‣ Dokumentation nicht noch bei „Context Match“
einblenden, sondern Notifications pro Dokument in
Outline-View oder neben Zeilennummer im Editor
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 20 / 20

52. 05 Ausblick
Mögliche zukünftige Arbeiten
‣ Einbindung verschiedener Source Code Reasoner
‣ Dokumentation nicht noch bei „Context Match“
einblenden, sondern Notifications pro Dokument in
Outline-View oder neben Zeilennummer im Editor
‣ Generierung einer offline Hypertext basierten
Dokumentation vgl. JavaDoc (einfachere Verbreitung)
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 20 / 20

53. DANKE
für Ihre
Aufmerksamkeit
TU Dresden, 14.02.08 Diplomverteidigung - Rule Based Documentation 20