Quellcode Kommentieren

[Bernhard Geyer]

Zitat von Dejan Vu:

Zitat:

ISO 13485 entwickeln, da gibt es kein SW-Release ohne Doku.

Das betrifft doch nur die Doku und keine Quellcode-Kommentare, oder irre ich mich?

Die Frage ist eher ob primär sinnvolle Doku entsteht oder nur Doku der Doku wegen?
Manche Normen produzieren viel Papier ohne eine mehrwert zu haben.

[himitsu]

Zitat von Bernhard Geyer:

Die Frage ist eher ob primär sinnvolle Doku entsteht oder nur Doku der Doku wegen?

Die nichtvorhandenen Einträge in der Delphi-Doku, wo nur drin steht, daß hier noch nichts drin steht.

[Sherlock]

Zitat von Dejan Vu:

Zitat:

ISO 13485 entwickeln, da gibt es kein SW-Release ohne Doku.

Das betrifft doch nur die Doku und keine Quellcode-Kommentare, oder irre ich mich?

Wir ziehen Teile der Doku aus dem Quellcode.
Doku der Doku wegen ist ne brisante Frage. Da muss man sich mit einem TÜV-ler oder echten Qualitätsmanager drüber unterhalten. Am Ende macht es Sinn, aber es ist verdammt schwer sich dran zu halten.

Sherlock

[Bernhard Geyer]

Zitat von Sherlock:

Doku der Doku wegen ist ne brisante Frage. Da muss man sich mit einem TÜV-ler oder echten Qualitätsmanager drüber unterhalten. Am Ende macht es Sinn, aber es ist verdammt schwer sich dran zu halten.

So wie tausende Seiten Pflichten/Lastenheft die jeden sch*** bis zum letzten Pixel beschreiben obwohl im länger dauernden Projekt (und das auch jeden klar ist) 95% dieser Dokumentation hinfällig wird.

[Hansa]

Dejan Vu hat Recht. Der beste Kommentar ist selbsterklärender Quelltext. Dann sind nämlich die Kommentare direkt "impementiert". Bei folgender Zeile einen solchen Kommentar zu schreiben ist völliger Schwachsinn :

procedure test; // das ist die Prozedur Test Hier allerdings (Pseudocode) :

Mwst := Mwst * 1.19; // Achtung : MWST. zu Testzwecken in EXE eincompiliert !! Muss noch geändert werden! 10.XXX Das wäre schon wichtig. Wobei das 10.XXX für Version steht. Dient halt zum Suchen im Source. Kann natürlich nach Belieben verfeinert werden. Und es gibt für solche Fälle direkt in Delphi ja auch noch ToDo.

[Nersgatt]

Zitat von Hansa:

Mwst := Mwst * 1.19; // Achtung : MWST. zu Testzwecken in EXE eincompiliert !! Muss noch geändert werden! 10.XXX

Da würde sich IMO eine Warnung eher anbieten:
{$message Warn 'Achtung : MWST. zu Testzwecken in EXE eincompiliert !! Muss noch geändert werden!'} Dann fällt es einem wenigsten bei jedem Erzeugen auf die Füße. Sofern das Fenster nicht sowieso mit Warnungen überquillt...

Im übrigens bin ich ganz der Meinung von dejan vu.

[sx2008]

Zitat von Sherlock:

Wir ziehen Teile der Doku aus dem Quellcode.

Da kommt es drauf an, für wen die Software geschrieben wird.
Wer ist die Zielgruppe?
Handelt es sich um eine normale Applikation, Webservice, Dienst der verkauft wird um bei Kunden installiert zu werden?
Dann braucht man diese Art von Doku nicht.
Ist es eine Assembly,Unit,Klassenbibliothek die von anderen Programmierern eingebunden werden soll?
Dann gehört es dazu fast jeder public/protected Methode einen Kommentar zu verpassen und die API-Hilfe mit einem Tool erzeugen zu lassen.

[Hansa]

Ja, auch das ist richtig, aber mich stören trotzdem völlig unnötige Kommentare a la i:= i + 1; // erhöht den Zähler um 1 Wer das nicht versteht (also ohne Kommentar, der ist ohnehin fehl am Platze )

[bernau]

Zitat von Hansa:

Ja, auch das ist richtig, aber mich stören trotzdem völlig unnötige Kommentare a la i:= i + 1; // erhöht den Zähler um 1 Wer das nicht versteht (also ohne Kommentar, der ist ohnehin fehl am Platze )

Ich glaube wir sind uns alle einig, daß solche Kommentare unsinnig sind.

Aber es gibt Kommentare, die ausfürlicher sind als der "sprechende Procedurename". Und die sollte man verwenden.

Mein Code ist auch meist selbsterklärend. Aber manchmal gibt es "unsinnige Wünsche" von Kunden. So etwas kommentiere ich immer. Teilweise sogar mit Verweis auf die E-Mail des Kunden. Hat mir in der letzten Zeit schon manches Grübeln erspart.

[Dejan Vu]

Zitat von bernau:

Aber manchmal gibt es "unsinnige Wünsche" von Kunden. So etwas kommentiere ich immer. Teilweise sogar mit Verweis auf die E-Mail des Kunden.

Wir machen das über CVS.