Forum: PC-Programmierung Code Dokumentation


Announcement: there is an English version of this forum on EmbDev.net. Posts you create there will be displayed on Mikrocontroller.net and EmbDev.net.
von Rev12345 (Gast)


Lesenswert?

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.

von Walter T. (nicolas)


Lesenswert?

Merker, weil mich die Antwort interessieren würde

von Patrick C. (pcrom)


Lesenswert?

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

von Rev12345 (Gast)


Lesenswert?

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".

von Rev12345 (Gast)


Lesenswert?

@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.

von Mladen G. (mgira)


Angehängte Dateien:

Lesenswert?

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
von Entlauser (Gast)


Lesenswert?

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).

von was für standards (Gast)


Lesenswert?

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.

von Experte (Gast)


Lesenswert?

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.

von Mladen G. (mgira)


Lesenswert?

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?

von Walter T. (nicolas)


Lesenswert?

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
von TGIF (Gast)


Lesenswert?

Clean Code.

von Entlauser (Gast)


Lesenswert?

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.

von Entlauser (Gast)


Lesenswert?

*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?"
 ...

von rbx (Gast)


Lesenswert?

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..!"

von Patrick C. (pcrom)


Lesenswert?


von Entlauser (Gast)


Lesenswert?

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/

von Walter T. (nicolas)


Lesenswert?

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.

von Fpgakuechle K. (fpgakuechle) Benutzerseite


Lesenswert?

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.

von DoS (Gast)


Lesenswert?

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.

von Framulestigo (Gast)


Lesenswert?

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.

von rbx (Gast)


Lesenswert?

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..

von Andras H. (kyrk)


Lesenswert?

> 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.

von Johannes S. (jojos)


Lesenswert?

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.

von A. S. (achs)


Lesenswert?

Gute Dokumentation kann man nicht an Metriken festmachen. Genauso wenig 
wie gute Gedichte

https://youtu.be/y5Cb1byNpmQ

Höchstens relativ

von A. S. (achs)


Lesenswert?

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.

Antwort schreiben

Die Angabe einer E-Mail-Adresse ist freiwillig. Wenn Sie automatisch per E-Mail über Antworten auf Ihren Beitrag informiert werden möchten, melden Sie sich bitte an.

Wichtige Regeln - erst lesen, dann posten!

  • Groß- und Kleinschreibung verwenden
  • Längeren Sourcecode nicht im Text einfügen, sondern als Dateianhang

Formatierung (mehr Informationen...)

  • [c]C-Code[/c]
  • [code]Code in anderen Sprachen, ASCII-Zeichnungen[/code]
  • [math]Formel in LaTeX-Syntax[/math]
  • [[Titel]] - Link zu Artikel
  • Verweis auf anderen Beitrag einfügen: Rechtsklick auf Beitragstitel,
    "Adresse kopieren", und in den Text einfügen




Bild automatisch verkleinern, falls nötig
Bitte das JPG-Format nur für Fotos und Scans verwenden!
Zeichnungen und Screenshots im PNG- oder
GIF-Format hochladen. Siehe Bildformate.

Mit dem Abschicken bestätigst du, die Nutzungsbedingungen anzuerkennen.