[php] 1/2 OT: gibt es einen Standard zur Kommentaren im Quellcode

[Oliver "Hypergrip" Richter]

> Hallo Liste,

Moin



> ich habe eine Frage zu Kommentaren im Quellcode.
> Im Augenblick habe ich einen Streit mit einem Auftraggeber, der nicht
zahlen
> will, weil er behauptet der Quellcode sei nicht ausreichend kommentiert
und
> somit für dritte nicht nachvollziehbar. Im Lastenheft ist nichts vermerkt
> über Vereinbarungen, wie die Kommentare auszusehen haben.
> Meine Frage: Gibts einen Standard wie ein Quellcode kommentiert sein muss?
> Würde mich interessieren, wie Eure Erfahrungen darüber sind?
> Kann es im Falle eines Rechtstreits an den Kommentaren liegen, daß ein
> Auftraggeber nicht bezahlen will?

Ich muss vorausschicken, dass ich keinerlei rechtliches Hintergrundwissen
habe und bisher noch nicht in so einer Situation war.
Ich kommentiere diese Sache also aus der Perspektive meines eigenen
Rechts-Bewusstseins, was nicht unbedingt mit der deutschen Gesetzgebung
überinestimmen muss.

Ich würde sagen, dass in erster Linie der Vertrag, den du mit deinem
Auftraggeber geschlossen hast, die oberste Instanz ist.
Dabei wäre es schonmal hilfreich zu wissen, welches Produkt bzw welche
Dienstleistung du deinem Kunden angeboten bzw verkauft hast.

War die Aufgabe z.B. eine dynamisch Lösung für eine Website zu programmieren
oder anzupassen (z.B. Firma XYZ will auf ihrer Website einen einfach zu
pflegenden Produktkatalog eingebaut haben), wüsste ich nicht, warum der
Kunde darauf ein Anrecht haben sollte, dass die gelieferte Lösung für ihn
leicht verständlich bzw nachvollziehbar ist.
Ich setze natürlich vorraus, dass in so einem Fall der Kunde ausreichende
Dokumentation und genügend Support erhällt, um das gelieferte Produkt
installieren und bestreiben zu können.
Hierbei steht natürlich vielleicht auch der Gedanke im Hintergrund, dass der
Kunde irgendwann mal einen Ausbau der Funktionspalette haben möchte... und
dann sollte er doch bitte wieder zum unsprüglichen Programmierer kommen
anstatt kostengünstig seinen eigenen Admin da dranzusetzen ;)

Anders sähe die Sache sicher aus, wenn es sich bei dem Produkt um eine Art
"Prototyp" handelt, also um ein Produkt, welches der Kunde als Basis für
weitere Entwicklungen nutzen will.
Wenn Firma ABC z.B. Webauftritte verkauft, es aber selber nicht auf die
Reihe bekommt, einen vernünftigen Webshop zu programmieren, kommen sie zu
dir und kaufen von dir einen Webshop-Rohling, den sie dann anpassen und in
ihren Produkten einbauen können. (Ja ok, das Beispiel ist vielleicht etwas
weit hergeholt, ich hoffe aber, es ist anschaulich).
In so einem Fall ist natürlich eine ausreichende Dokumentation der
Funktionsweise deines Produktes nötig... sei es nun als 50-Seiten-Anleitung
und/oder eben als Quelltext-Kommentare.

Dies sollte aber im Vorfeld geklärt worden sein.
Man macht ja nicht umsonst eine Bedarfs-Analyse, erstellt ein Pflichten-
bzw- Lastenheft und unterhällt sich mit dem Kunden über dessen Vorstellungen
und Wünsche.
Wenn bei deinem Projekt in keiner dieser Phasen deutlich wurde, dass dein
Produkt für dritte leicht verständlich sein muss, wüsste ich nicht, warum
dein Kunde irgendein Recht haben sollte, dein Produkt nicht zu bezahlen.


Kleine Notiz zum Kommentieren an sich:
da ich zur Zeit noch Student bin (und wohl, Mathe sei Dank, in ein paar
Monaten abbrechen muss), bin ich es gewohnt, meinen Code an wichtigen
Stellen zu kommentieren, um meinen DOzenten bei der Abnahme zeigen zu
können, ob ich die Schlüsselstellen richtig erkannt habe usw.
Ich glaube nicht, dass es einen offiziellen Standard zur Kommentierung gibt,
denn meiner Meinung nach dient die Kommentierung in erster Linie allein der
Planung, Ordnung und Übersicht des Programmierers in seinem eigenen Code.
Arbeitet man mit mehreren Leuten an einem Projekt hilft eine gewisse
Standartisierung natürlich auch weiter.

Eine Kommentierung, die auch Dritte möglichst einfach verstehen ist meiner
Erfahrung nach bei Projekten, die ein gewisses Lehr-Zeil haben,
unabdingbar... nud die meisten Open-Source projekte kommentieren ihren Code
ebenfalls sehr brauchbar, was halt mit der Grundidee von Open-Source zu tun
hat.
die wenigen kommerziellen Quellcodes, in die ich bisher schauen konnte (wenn
auch nur Teile davon) waren sehr schlecht, wenn überhaupt, oder gar kryptish
kommentiert.
Mein persönlicher Stil der Kommentierung geht von "Aufgaben"-Kommentaren a
la "Beginn 2. Abfrage (Gültigkeit der User-ID)" über eine Art
ungangssprachlichen Quelltext "wenn cookie nicht gesetzt, dann Menu3
anzeigen" bis hin zu Kommentaren, die fast schon kryptisch anmuten und sich
auf irgenwelche Beizeichnungen an anderer Stelle im Project beziehen, wie
z.B. "I1 uid auf u,p,t und c, (m1,m2 oder f1)".



> Aus Respekt vor den Teilnehmern der Liste bitte die Antworten nicht an die
> Liste senden, sondern bitte per PM an php.liste at net-service-24.de

Ich halte es für sinnvoll, das ganze ruhig hier weiterzudiskutieren, es
hilft anderen sicher auch weiter, falls sie mal in so eine Situation
geraten. man lernt halt auch ganz gerne aus Erfahrungen/Fehlern anderer
Leute. Und ganz uninteressant ist das Thema auch nicht, obwohl etwas OT.



> Gruss Roland

Gruss Oliver