Doc-o-Matic

Computer: Software & Programmierung Programmierung allgemein
#1

Hallo,

Ich möchte mit einem Metriktool die Kommentare in einem Sourcefile zählen, dabei soll eine Aussage getroffen werden, wieviel Kommentare „händisch“ erstellt wurden.
Das reine zählen aller Kommentare führt bei Kommentaren, die mit solchen Tools erstellt wurde zu Fehlinterpretationen, da ja ein beträchtlicher Teil automatisch erstellt wird.

Kann man da irgendeine Unterscheidung treffen ?
Wenn nicht, gibt es evtl. eine feste Anzahl an Zeilen in solch einem Kommentarblock die 100% aus solch einer Zählung ausgelassen werden können ?

Ich konnte das Tool leider nicht testen, habe auch keine Beispielcodes, brauche aber diese Information.

MfG
MK

#2

Hallo MK,

Kann man da irgendeine Unterscheidung treffen ?

  1. Kannst du unterscheiden welche Kommentare von Hand geschrieben wurden und welche von Generator ??

Wenn NEIN, kannst du das auch keinem Programm beibringen.
Wenn JA, dann erstelle Regeln und erstelle ein entsprechendes Programm.

Kleiner Tip: Wenn man Zugriff auf die Textblöcke des Generators hat, wird es einfacher …

MfG Peter(TOO)

#3

Hallo,

eine nachträgliche Unterscheidung dürfte es wohl nicht geben, daher sehe ich nur 2 Möglichkeiten:

  1. Die Entwickler werden angewiesen, jeden Kommentar mit ihrem Namen zu kennzeichnen. Ist auch sonst keine schlechte Idee.

  2. Jedes Konstrukt wird mit der Ursprungsfassung vor der Ergänzung durch den Programmierer verglichen. Ist bei der möglichen Anzahl verschiedener Konstrukte wahrscheinlich nicht durchführbar.

Was Peter meint, ist die Umkehrung von 1 - die Autokommentare werden gekennzeichnet. Ich bezweifle aber, dass das weniger Arbeit ist.

Gruss Reinhard

[Bei dieser Antwort wurde das Vollzitat nachträglich automatisiert entfernt]

#4

Hallo Reinhard,

Was Peter meint, ist die Umkehrung von 1 - die Autokommentare
werden gekennzeichnet. Ich bezweifle aber, dass das weniger
Arbeit ist.

Eigentlich war das als Denkanstoss gedacht !
Wenn schon MK das nicht unterscheiden kann, wie soll es dann der Computer verstehen ??
Alo muss, wie du geschrieben hast, irgendein Kriterium geschaffen werden.

Allerdings schreibt der MK auch nicht was für ein Tool er verwenden will und ob man diesem das auch irgendwie beibringen kann.

MfG Peter(TOO)

#5

hi mario

hilfreiche informationen deinerseits wären:

  • verwendete programmiesprache
  • verwendete entwicklungsumgebung
  • verwendetes metriktool

da es teilweise extreme unterschiede gibt, wie kommentare aussehen bzw. welche kommentare automatisch eingefügt werden, ist jede aussage der community automatisch wertlos, sofern diese angaben unbekannt bleiben.

ansonsten ist es durchaus nicht unüblich, einfach die kommentarzeilen zu zählen und einen gewissen prozentsatz an angenommenen automatischen kommentarten abzuziehen. da die anzahl der kommentare sowieso nix über die qualität der kommentare aussagt, ist das durchaus ein gangbarer weg.

es gibt ja durchaus die denkschule, dass immer dann, wenn der quellcode einen kommentar erfordert, man besser aus diesem block eine subroutine macht. wirklich gute programme sind auch ohne kommentare gut lesbar. andererseits kenne ich genug programme, die zu mehr als 60% aus kommentaren bestehen. diese kommentare sind aber von der qualität á la „function getName() // get the name of object“, sind also eher kontraproduktiv.

einfach nur ein metrikprogramm über den sourcecode zu jagen und daraufhin rückschlüsse auf die qualität des codes zu ziehen ist in manchen fällen eher gefährlich!

erwin

#6

Also zur Angabe der Sprache, es sollen Basic,C++/C# (.Net), AWL,Perl (Editor) ausgewertet werden.
Daher hab ich keine Sprache angeben, da ich eine allgemein gültige Lösung brauche.

Ich habe eigentlich eine Antwort erwartet die direkt auf Doc-o-Matic abzielt. Mir wurde gesagt, die Kommentare sind in dem eigentlichen Quelltext nicht sichtbar, sondern werden über Metadaten von Doc-o-Matic verwaltet. Der Entwickler arbeitet ganz normal in seiner Umgebung, Kommentare werden automatisch beim Definieren einer Funktion erstellt, der Entwickler füllt diese aus. Tatsächlich werden diese Kommentare in .dox-Files gespeichert (woraus dann formatierte Kommentare - HTML usw. - erstellt werden können). Hoffe das stimmt so.

Das Metrik-Tool das zum Ensatz kommt wird vom Hersteller an unsere Wünsche angepasst und sollte dann wohl diese Metadaten auch interpretieren können, dazu müsste wohl eine Art Plugin vom DOM-Hersteller in das Metriktool eingebaut werden…falls das so realistisch, viel zu kompliziert.

Die Lösung, eine Anzahl automatisch generierter Zeilen anzunehmen ist dann wohl doch ausreichend (hätt ich auch selbst drauf kommen können :smile:)

„einfach nur ein metrikprogramm über den sourcecode zu jagen
und daraufhin rückschlüsse auf die qualität des codes zu
ziehen ist in manchen fällen eher gefährlich!“
vollkommen richtig, vor allem bei Scriptsprachen wie Perl.

MfG u. Danke

[Bei dieser Antwort wurde das Vollzitat nachträglich automatisiert entfernt]

#7

mea culpa
hi mario

kannte doc-o-matic nicht, habe mich aber eben schlau gemacht. offenbar fügt doc-o-matic automatische kommentare bei methoden ein, die dann zusätzlich erweitert werden können. da die kommentare offenbar in einer eigenen datei gespeichert werden, sollte es schon möglich sein, die automatisch erstellten von den manuellen zu unterscheiden. ist allerdings eine etwas mühsehliche angelegenheit, da man zuerst herausfinden muss, welche kommentararten doc-o-matic insgesammt automaitsch erstellen kann. dann muss man mit aufwändigen suchmustern diese rausfiltern.

ich denke, es ist einfacher, ein kleines beispiel-programm zu erstellen (nur auf funktionen bestehend - keine logik) und dieses automatisch kommentieren zu lassen. anschließend zählt man die anzahl der kommentare, dividiert durch die anzahl der methoden und erhält ungefähr eine durchschnittliche anzahl an kommentarzeilen pro methode.

dann nimmt man ein echtes programm her, zählt die anzahl der methoden (sollte ein klax für das metrik-tool sein), multipliziert mit dem obigen wert und zieht diesen wert von der anzahl der kommentarzeilen ab.

das ergebnis ist zwar bei weitem nicht genau, aber wie schon erwähnt kann selbst ein genau ermittelter wert bestenfalls ein anhaltspunkt sein. sinnvoller wäre es, die automatisch generierte dokumentation von einem anderen programmierer querchecken zu lassen. kennt sich der damit aus, ist die doku ok (egal wie lang), kennt er sich nicht aus, ist die doku müll (wiederum egal wie lang).

erwin