Hallo, ich muss im Rahmen eines Projektes die Dokumentation eines anderen Softwareprojektes bewerten. Das bedeutet uns wurde die Doku inkl. Quellcode übergeben und wir sollen bewerten, ob der Quellcode ausreichend dokumentiert worden ist, so dass ein Dritter mit dieser Doku bzw. Quellcode weiterentwickeln kann. Jetzt ist meine Frage: Gibt es für den Review einer Quellcode-Dokumentation eine Art Norm bzw. Bewertungskriterium? Vielen Dank im Voraus.
Ich denke man musz etwas weiter gucken nach Code Quality und nicht nur wie die code dokumentiert ist. Um welche programiersprache geht es ? Vielleicht gibt dieses einige informationen [sorry in English] https://www.perforce.com/blog/sca/what-code-quality-and-how-improve-code-quality Grusz Patrick aus die Niederlaende
Also an sich ist es PHP (ja, ich weiß, dass es dann keine wirkliche Software ist). Wenn es aber eine Norm für die Bewertung einer Softwaredokumentation gibt dann kann man so etwas auch auf die Doku einer Webanwendung, die in PHP geschrieben worden ist mehr oder weniger "ummünzen".
@pcrom: Die seite kenne ich bereits. Leider ist die Seite nicht das, was ich suche. Ich suche nach einer Norm, auf die man sich auch in einem offiziellen Arbeitspapier beziehen kann.
Angehängte Dateien:
-
Code_Quality.jpeg
48 KB
Den einzig wahren internationale Standard für die Bewertung von Code und Dokumentation siehst du im Anhang/Bild. Ansonsten ist es ganz einfach: Kannst du mit dem Code/Doku arbeiten? Liegt es an dir oder an der SW oder an der Doku? Was ein Dritter mit dem Code und der Doku anfangen kann, liegt am Dritten ;)
:
Bearbeitet durch User
Rev12345 schrieb: > Jetzt ist meine Frage: Gibt es für den Review einer > Quellcode-Dokumentation eine Art Norm bzw. Bewertungskriterium? Sicher, aber wenn du nicht selbst Bewertungskriterien aufstellen kannst, bist du für das Projekt komplett ungeeignet. So wie ein Milchreisbubi, der die Gebrauchseigenschaften von verschiedenen Tampons bewerten soll. Beginn doch damit, das du beschreibst wie Du deinen eigenen Code dokumentierst (oder dokumentieren würdest) das er weiterentwickelbar ist. Wahrscheinlich indem du beschreibst, was der Code machen soll (Spec.), wie er das tut was er tun soll (Implementierungsbeschreibung) und wie er sich in die Gesamtstruktur einsortieren lässt (Schnittstellen, Software-Architektur).
z.B. wie bei doxygen. Vor jeder Funktion, Klasse, etc. mit tags @details, @param, @return, etc. beschreiben was die Funktion macht, welche Parameter an die Funktion übergeben werden, was die Funktion zurückgibt, usw.. So dasss man am Ende sogar eine eigene Dokumentation-Datei erstellen kann.
Entlauser schrieb: > So wie ein Milchreisbubi, > der die Gebrauchseigenschaften von verschiedenen Tampons bewerten soll. Genau so sieht es aus. Wenn man die Arbeit von jemanden anderen bewerten möchte, braucht man mehr Wissen und Erfahrung als der Autor der zu bewertenden Ergüsse. Ist eigentlich ein ganz simples, uraltes Prinzip. Verstehen heute nur viele nicht (mehr). Und selbst wenn es eine Norm gäbe, wäre das nur weiteres nutzloses Papierwerk, mit dem wiederum nutzlose Papierwerk in Form von Bewertungen produziert würde. In der Norm würde etwa stehen "Jeder Parameter muss beschrieben werden". Der Bewerter würde dann einfach abzählen, wie viele Parameter beschrieben wären und wie viele nicht. Nur: Das wäre vollkommen nutzlos, weil es nur die Quantität misst und nicht die Qualität.
Experte schrieb: > Wenn man die Arbeit von jemanden anderen bewerten möchte, braucht man mehr Wissen und Erfahrung als der Autor der zu bewertenden Ergüsse. > > Ist eigentlich ein ganz simples, uraltes Prinzip. Verstehen heute nur > viele nicht (mehr). Ja, u.a. Dunning–Kruger Effekt. Ist IMO aber eine kulturelle Frage, damit meine ich die Firmenkultur, darf man zB. sagen "das verstehe ich nicht" oder gar "das weiss ich nicht"? Oder muss man dann so tun als ob man es weiss/kann?
Dokumentation sichten ist undankbare Fleißarbeit, die sich nicht ernsthaft automatisieren lässt, weil es keine brauchbare Metrik gibt. Cargo-Cult-"Dokumentation" sichten ist noch schlimmer. Und dann noch Doku eines Fremden sichten, um es einem weiteren Fremden übergeben zu können? Das klingt nach Rettung eines missglückten Projekts bei minimalem Kostenaufwand. Für mich sieht das nach einer typischen Bachelorarbeit eines Werkstudenten aus. (Oder eines verzweifelten Studenten, der keine bessere Arbeit bekommt.) Und da ist die Frage nach sinnvollem Lesestoff und Normen absolut gerechtfertigt.
:
Bearbeitet durch User
Walter T. schrieb: > Für mich sieht das nach einer typischen Bachelorarbeit eines > Werkstudenten aus. (Oder eines verzweifelten Studenten, der keine > bessere Arbeit bekommt.) Und da ist die Frage nach sinnvollem Lesestoff > und Normen absolut gerechtfertigt. Es wird aber nicht der Sache gerecht einem unbedarften Studenten die Bewertung einer fremden Software zu überlassen. Wer als Projektleiter 'sowas' tut, ist nicht weniger unbedarft als der Student. Da sollte man wenigstens mit gutem Beispiel voran gehen und die ersten 10% des Codes gemeinsam reviewen. Damit der beauftragte Student ne Chance hat den Inhalt des Arbeitsauftrages "Code Dokumentation bewerten" zu erfassen. Und als Projektleiter auf irgendeine Norm zu verweisen um seine Ruhe zu haben, hilft da auch nicht weiter, sondern legt nur die Inkompetenz hinsichtlich des Inhaltes von Normen und den Anforderungen an einen Review offen. Von mangelnder Eignung als 'Vor- resp. Leit-bild' ganz schweigen.
*Cheffe:* "Morgen führe ich potentielle Auftraggeber durch die Büroräume. Es wäre hilfreich, wenn ihr dafür aufräumt und morgen ordentlich erscheint". *Belegschaft:* "Gerne, nach welcher Norm sollen wir aufräumen und wo können wir zu ordentlichen Auftreten nachlesen?" ...
Bill Blunden hatte in seinem Rootkit-Arsenal-Buch die Dimensionen: poorly documented partially documented not documented man könnte eventuell noch eine Häufigkeitstabelle anwerfen und Monitoring betreiben, wie oft - WTF, was ist das hier? (s.o.) - LOL - Merkwürdig Dann gibt es noch selbsterklärenden Code (vorsicht!), also zum Beispiel wenn man heute eine Internetseite anschaut, dann auf die Quellansicht klickt, und anschließend sowas denkt wie "ja, alles klar..!"
TGIF schrieb: > Clean Code. Einverstanden, gutes Buch https://www.bol.com/nl/nl/f/clean-code/9200000033313462/
Patrick C. schrieb: > TGIF schrieb: >> Clean Code. > Einverstanden, gutes Buch Besser das, weil 'ganzheitlich' (Nicht auf einen Code-style beschränkt) und in 'Alltagsdeutsch' geschrieben und schon im Titel realistischer im Anspruch: ISBN: 978-3-89721-567-2 Zugehörige Rezensionen (Auswahl): https://www.heise.de/developer/artikel/Weniger-schlecht-programmieren-2173247.html https://www.lehmanns.de/shop/mathematik-informatik/20199927-9783897215672-weniger-schlecht-programmieren https://www.hackerspace-bremen.de/2014/03/24/buchrezension-weniger-schlecht-programmieren/
Entlauser schrieb: > Es wird aber nicht der Sache gerecht einem unbedarften Studenten die > Bewertung einer fremden Software zu überlassen. > Wer als Projektleiter 'sowas' tut, ist nicht weniger unbedarft als der > Student. Das läuft dann üblicherweise so ab: Der Student arbeitet fast nur auf Auftrag für die Firma. Und dann muss er sich selbst noch die passende Theorie zusammensuchen, um den Theorieteil für die Arbeit zu füllen. Aber nicht vergessen: Das mit der Bachelor-Arbeit ist geraten. Vielleicht ist es hier etwas ganz Anderes.
Rev12345 schrieb: > Jetzt ist meine Frage: Gibt es für den Review einer > Quellcode-Dokumentation eine Art Norm bzw. Bewertungskriterium? Vielleicht findt man ja was unter den "Anforderungen an eine Anschlussarbeit an der Fakultät Informatik" Da besteht der Schriftteil ja grösstenteils aus Dokumentation einer Programmierarbeit. https://www.in.th-nuernberg.de/Professors/Weber/Abschlussarbeit%20Methodik.pdf Da mal ein Pamphlet zur "Automatisierten Dokumentation": https://swa.informatik.uni-hamburg.de/files/abschlussarbeiten/Diplomarbeit_EJ_Oezkan.pdf Das scheint den Ansatz zu verfolgen, es wäre notwendig den Code nur aus sich selbst zu dokumentieren.
Rev12345 schrieb: > Hallo, > ich muss im Rahmen eines Projektes die Dokumentation eines anderen > Softwareprojektes bewerten. Das bedeutet uns wurde die Doku inkl. > Quellcode übergeben und wir sollen bewerten, ob der Quellcode > ausreichend dokumentiert worden ist, so dass ein Dritter mit dieser Doku > bzw. Quellcode weiterentwickeln kann. > Jetzt ist meine Frage: Gibt es für den Review einer > Quellcode-Dokumentation eine Art Norm bzw. Bewertungskriterium? > Vielen Dank im Voraus. Eigentlich gibst Du die wichtigste Antwort selbst: Kann ein Dritter mit vertretbarem Einarbeitungsaufwand den Code weiterentwickeln? Versuche einfach, das für einige Bereiche zu machen. Entstehen dabei mehr Fragen und Seiteneffekte und Du musst "reverseengineeren", ist der Code schlecht strukturiert und schlecht dokumentiert. Doxygen ist ganz nett, aber meiner Ansicht nach ein Anfang. Alle Ingenieure hassen es zu dokumentieren, und alle jammern und wehklagen über fehlende Dokumentation der Anderen.
Ich glaube fast, aus der Nummer kommt man am besten mit dem Schreiben eines Tests raus (bringt beiden Seiten was). Einfach machen, was in der Doku steht und die Güte anhand der Testergebnisse bewerten.
Fpgakuechle K. schrieb: > Vielleicht findt man ja was unter den "Anforderungen an eine > Anschlussarbeit an der Fakultät Informatik" Da besteht der Schriftteil > ja grösstenteils aus Dokumentation einer Programmierarbeit. > > https://www.in.th-nuernberg.de/Professors/Weber/Abschlussarbeit%20Methodik.pdf > > Da mal ein Pamphlet zur "Automatisierten Dokumentation": > https://swa.informatik.uni-hamburg.de/files/abschlussarbeiten/Diplomarbeit_EJ_Oezkan.pdf +1 ziemlich gute Links sind das. Man fragt sich tatsächlich auch, was sind das eigentlich für Leute, die das Manual und die Übersetzungen für Debian schreiben? Ziemlich gute Programmierer nach der Folklore https://www.bernd-leitenberger.de/echte-programmierer.shtml höchstwahrscheinlich nicht..
> Jetzt ist meine Frage: Gibt es für den Review einer > Quellcode-Dokumentation eine Art Norm bzw. Bewertungskriterium? Beileid... Tut mir leid dass du so etwas machen musst. Normaler weise wenn der Source Code da ist, kommt eine sehr gute Entwickler damit aus. Ich persönlich lese keine Dokus mehr, eher den Source Code. Manchmal ohne Source Code lese ich den Disassembly davon. Passt auch. Die 3rd Party Zulieferers gucken dann ein bisschen, aber dann gewöhnen Sie sich daran. Ich gebe noch den Kommentar ab, ja es wäre viel einfacher zu debuggen wenn der C Code da wäre, also nächstes mal bitte den auch mitschicken. Sonst bei Treibergeschichten muss man ja den uC Dantenblatt schon mal angucken. Wobei bei 3000 Seiten ist es auch eher Ctrl-F und suchen Ich verstehe auch nicht was man da gross an C code kommentieren kann. Funktionsname kann sehr viel schon sagen. Die Parameters auch. Die Datentypen auch. Soll man das noch einmal runter schreiben, hey der Parameter ID ist eine ID mit datentyp ID. Viel Sinn macht das eh nicht. Suchzyklen kann man auch so gestalten, dass man da schon weiß, ja mit der ID wird aus eine Liste einen Eintrag gesucht. Das noch extra hin zuschreiben mach nicht viel Sinn. Wer das aus dem Code nicht alleine versteht der wird das aus dem Kommentar auch nicht. Man kann alles Kommentieren, letztendlich für mich ist das eh etwas was ich nicht angucke, aber von mir aus können andere gerne da Zeit investieren. Viel wichtiger ist, dass der Code selber schon zeit was man da machen möchte. Und nicht so aussieht wie ein foo() bar() scheiß. Gescheite Namen, Datentypen und schon strukturierte Header Files.
in D gibt es doch für alles Normen, googeln nach 'din software dokumentation' bringt z.B. https://www.tekom.de/technische-kommunikation-das-fach/wichtige-normen-der-technischen-kommunikation/softwaredokumentation Persönlich wünsche ich mir erstmal eine Übersicht, möglichst grafisch. Tiefergehend dann Modul/Funktions/Objektbeschreibungen. Vielfach wird das ja aus Quellcodebeschreibungen generiert und man findet zu 'motorOn()' die Beschreibung 'schaltet Motor ein'. Sowas ist sehr kreativ und hilfreich... Schön wären weitere Informationen, Randbedingungen, Limits für Argumente, Abläufe. Aber das ist viel Arbeit und immer der letzte Punkt auf der Todo Liste. Weil bei uns auch gerade darüber diskutiert wurde: wie kann man GitLab und Confluence (Wiki) gut verknüpfen für Projektdoku? Einen Teil Doku kann man einfacher im Wiki editieren, aber die Doku ins Projekt integriert als Markdown/HTML hat den Vorteil das sie beim auschecken gleich in der richtigen Version vorhanden ist.
Gute Dokumentation kann man nicht an Metriken festmachen. Genauso wenig wie gute Gedichte https://youtu.be/y5Cb1byNpmQ Höchstens relativ
Johannes S. schrieb: > Einen Teil Doku > kann man einfacher im Wiki editieren, aber die Doku ins Projekt > integriert als Markdown/HTML hat den Vorteil das sie beim auschecken > gleich in der richtigen Version vorhanden ist. Irgendwie fehlt den meisten Doku-Ansätzen so eine Art Gilb und Knitter. In Papier-Doku hatte man ein Gefühl, wie alt (Druckbild, Papier, Gilb, ...), wie häufig gebraucht (Eselsohren, glatt, ...) und wie kontrovers (handschriftliche Korrekturen, durchgestrichen, ...) etwas ist. Bei Wiki und Code könnte man zu jeder Passage nachschauen, wie viele daran gewerkelt haben, aber wer macht das schon. Oder anders: Bei Doku kann ich sorgfältig zusammengestellte Hinweise mit hoher Info-Dichte nicht von lieblos hingeklatschtem Text unterscheiden, der inzwischen veraltet und auch davor größtenteils falsch war. Mir würde schon eine Selbsteinschätzung reichen, so von "Pflichtprogramm" bis "Herzblut", dargestellt z.B. als hellgrau bis weißer Hintergrund. Nur verkündet dann wieder jemand, dass bei ihm natürlich alle "Herzblut" liefern werden.
Thread beobachten
Seitenaufteilung abschaltenBitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.