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

[mhe]

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

hi,

zum thema standards kommentare, da gibs nix,
nur konenventionen und paradigmen,
http://pear.php.net/manual/en/standards.comments.php

wen du meinst alle abnahmekriterien erfuellt zu haben und
keine maengel bestehen, schicke die rechnung. auf alle
faelle schicke sie.

wen dein AG behauptet, er sei nicht ausreichend dokumentiert
ist das schoen fuer Ihn, behaupten kanner ja viel. es ist
nirgends definiert, was ausreichend bedeutet .. du hast
es in deinem sinne fuer ausreichend fuer dritte dokumentiert,
mache das deutlich, dokumentieren kann auch viel heissen,
das kann gehen von jeder zeile bis hin zu strukt-gram, er modell
was weiss ich ..

bei mir stand auch immer drinne "dokumentieren quellcode"
aber nicht wie, da habe ich folgendes gemacht schon waehrend des projektes ..

mir den code genommen von allen klassen und func sammlungen,
die phpdoc like kommentiert, rudimentaer, dauert einen tach im nachhinein, wenn man muss maximal ..

dann noch jede datei die man hat getagged mit phpdoc,
und kurz was sie macht .. sinnvoll eigentlich

dann mit phpdoc generiert als "one page html", das ins schreibprogramm
importiert und ausgedruckt .. nicht elektronisch liefern .. kamen 500 seiten
raus .. richtiges papier macht sich da immer gut ..

papier ist magie !!!!!!!!!!

dann habe ich noch mit http://www.casestudio.com die db sowiesoschon entwickelt
und dort auch mit kommentaren versehen die tabellen und attribute,
hauptsache es steht was da ..

das nach schreibprogramm exportiert, auch ausgedruckt, waren 200 seiten.

papier ist magie !!!!!!!!!!

das ganze habe ich dann genommen in 3 grossen A4 Ordnern, schoen beschriftet,
und mit zur Abnahme genommen .. waren 700 seiten ..

papier ist magie !!!!!!!!!!

* damit ist erkennbar das du dir arbeit beim dokumentieren gemacht hast, sprich aufwand hattest
und konkludent gehandelt hast, sprich im sinne des auftrages
* mache deutlich das keine anforderungen bestanden und du dir das so denkst, schriftlich
* da du aufwand hattest, ein werk entstanden ist in form der doku, abnahme sollte dem nichtsmehr im wege stehen, schriftlich abnahme mit unterschrift
* moechte dein AG eine andere form der doku, ist dies mit erneutem aufwand verbunden, sprich mehrkosten neuer auftrag, mache ihm ein angebot dazu, schriftlich

frage ihn auf keinen fall, wie er sich die doku vorstellt, waehle den dir schmerzfreiesten weg,
wen nichts definiert ist .. alles andere im nachhinein nach dem erstellen der doku wie auch immer,
erzeugt bei dir mehraufwand, den er nicht fordern kann ohne mehr zu bezahlen ..

normalerweise greifen bei nicht nennung von fakten die gesetzlichen regelungen, wenn nichts
ausgeklammert wird, dafuer gibt es aber keine gesetzliche grundlage wie im bauwesen z.bsp., also handelst du
IMMER in deinem eigenen interesse ..

ciao
 Mathias

ps. ohne gewaehr, das ganze bezog sich auf ein projekt in 2000/2001, mache sowas seit damals nichtmehr, da es sich
nicht lohnt und nur abzocker auf dem segment unterwegs sind, zumindestens habe ich nichts anderes kennengelernt ..

pss. aus dieser zeit resultiert auch meine erfahrung mit amts/landgerichten, richte dich schonmal drauf ein, das du bei
ner verhandlung mit nur 50% des streitwertes rechnen kannst .. je nach sachlage, die haben keine ahnung,
der entscheidende richter wird bei der vorverhandlung sagen "kann nicht beurteilen ob kommentare ausreichen, muessemer
im verfahren klaeren durch gutachter, ich schlage deshalb 50% des streitwertes vor oder verfahren(teuer,lange)"

psss. ob solch eine dokumentation wirklich sinn macht, ist eine andere frage .. ein entwickler sollte damit
aber zurechtkommen, steht halt alles da .. irgendwo

pssss. erwaehnte ich das papier magie ist ?