Tach,

frage, wie sieht denn euer Header (Kopf, Beschreibung) eurer Units/Proceduren aus.
Und welche beschreibung ist am Übersichtlichsten... !?

Meine Unit Beschreibung:

<!--pas--></span><table border='0' align='center' width='95%' cellpadding='3' cellspacing='1'><tr><td>Delphi-Source </td></tr><tr><td id='CODE'><!--pas1--><pre>
{-----------------------------------------------------------------------------

Project Name: radical <span class='integer'>3</span>D

<span class='reserved'>Unit</span> Name: r3d_texture

Author: Finalspace

Classes: TR3DTexture
TR3DTextureManager
TR3DTexcoord

-----------------------------------------------------------------------------}
</pre><!--pas2--></td></tr></table><span class='postcolor'><!--pas3-->

Meine Procedure Beschreibung:

<!--pas--></span><table border='0' align='center' width='95%' cellpadding='3' cellspacing='1'><tr><td>Delphi-Source </td></tr><tr><td id='CODE'><!--pas1--><pre>
{-----------------------------------------------------------------------------
<span class='reserved'>Procedure</span>: LoadTGATexture
Author: Finalspace
Date: <span class='integer'>01</span>-Apr-<span class='integer'>2003</span>
Arguments: Filename: <span class='reserved'>String</span>; <span class='reserved'>var</span> Texture: TGLuint; LoadFromResource : Boolean; _Detail : Byte
Result: Boolean
<span class='reserved'>Type</span>: global
Description: Texture aus einem TGA <span class='integer'>24</span> und <span class='integer'>32</span>bpp mit Alpha Kanal laden.
-----------------------------------------------------------------------------}
<span class='reserved'>function</span> LoadTGATexture(Filename: <span class='reserved'>String</span>; <span class='reserved'>var</span> Texture : TGLuint; _Detail : Byte; <span class='reserved'>const</span> _S3TC, Ani : Boolean): Boolean;
</pre><!--pas2--></td></tr></table><span class='postcolor'><!--pas3-->

Die Procedure Beschreibung ist Ok, finde aber die Unit Beschreibung zu kurz und zu undetailiert.
Was müsste man noch in ne Unit beschreibung reinmachen und wie siehts mit Lizenz vereinbarungen aus... muss man ne Lizenzbeschreibung in jede Unit machen ?


matane,
Final

ich benutze gar keinen header... ich bemühe mich den code so klar wie möglich zu schreiben so dass ich keine kommentare brauche. wo der code nicht verstänldich ist schreib ich per // was dazu. Ansonsten vermeide ich überflüssige Kommentare wie der Teufel das Weihwasser, da die das Arbeiten eher behindern als helfen.

_________________
Selber Denken macht klug!

Etwaige Lizenzen solltest du an einer logischen Stelle unterbringen - eine readme.txt eignet sich vorzüglich dazu. Während ich im Prinzip durchaus dafür bin, Codestellen mit Kommentaren zu versehen, sollte das Resultat der Mühe angemessen sein.
Das heißt
- bei der Umsetzung von komplexen Algorithmen, kann es dir bei einer späteren Fehlersuche helfen, wenn der Algorithmus in einfachen Worten als Kommentar dabei steht
- schwächelnde Codestellen und Hacks sollten mit einem ToDo Kommentar versehen werden, damit suboptimale ad-hoc Lösungen nicht bis ins hohe Greisenalter überleben

Wenn du Bibliotheken verteilst, ist eine Beschreibung der einzelnen Routinen und Datentypen durchaus nützlich - insbesondere auch das Zusammenspiel der einzelnen Funktionen untereinander. Die Delphi Hilfe - auch wenn sie manchmal Fragen offen läßt - empfinde ich als recht gut gelungen.

Pascal wurde als strukturierte Sprache entworfen, die teils bereits selbst erklärend sein sollte - IMHO bringt es nichts, selbstverständliche Informationen nochmal aufzurollen:


steht sowieso im Funktionskopf


Nur wichtig, wenn mehrere Leute an der selben Unit arbeiten


dito - und wenn du wirklich an einem Projekt mit vielen Leuten hängst, solltest du jede Änderung ohnehin mit einem Codeverwaltungsprogramm a'la SourceSafe dokumentieren und FallBack Versionen sichern


Steht doch alles im Funktionskopf


evtl. wichtig - bei lokalen Routinen mit Begründung warum sie nicht veröffentlicht werden


Beim wichtigen Teil hältst du dich dafür kurz , hier wären nun (bei Weitergabe der Unit) eine Beschreibung der akzeptierten Werte der einzelnen Parameter, sowie der Rückgabewerte, sowie evtl. geworfene Exceptions praktisch.
Wenn du deine Doku als Hilfedatei verfasst, wären auch noch Querverweise zu verwandten Themen angebracht

Was mir an deinen Funktionskommentaren gut gefällt, ist dass sie dazu geeignet sind, eine Routine von der anderen zu trennen - soll heißen beim schnellen drüberscrollen auf der Suche nach einer bestimmten Funktion, sind sie sicher praktisch.

Es geht bei der Sourcecodedokumentation weniger darum möglichst viel zu schreiben, als vielmehr mögliche Verständnisprobleme aufzudecken. Wenn ich (hauptsächlich früher - heute eh kaum mehr) Assembler programmiere, ist fast jede Zeile kommentiert, da in einem Assemblerlisting wirklich schwer zu erkennen ist, was nun die tatsächliche Funktion der einzelnen Kommandos ist.
In Pascal/Delphi sind es nur mehr Schlüsselstellen, vor allem bei komplexeren Algorithmen, da Pascal wirklich eine schön strukturierte Sprache ist, die fast als Pseudocode (der sonst für die Dokumentierung verwendet wird) durchgehen kann.

_________________
Viel Spaß beim Programmieren,
Mars
http://www.basegraph.com/

Ich benutze auch sehr wenig Kommentare und meistens nur als Gedankenstütze für Dinge die ich vergessen würde und die nicht aus dem Quelltext ersichtlich sind.
Ich schreibe manchmal an den Anfang einer Unit bestimmte Informationen, wie z.B. die wichtigsten Klassen oder neue Ideen.
Außerdem trenne meistens ich die Methoden einer Klasse von anderen Methoden im Implementationsteil durch Kommentare der Form // Klassenname.
Das ist aber alles ganz informell. Jeder muß selber wissen wie er am Besten zurecht kommt. Im Quelltext der VCL sind auch meistens nur kurze Kommentare.
Anstelle die Paramter einfach noch mal aufzulisten könnte man beschreiben, was sie bedeuten. Es ist z.B. nicht sofort deutlich was _detail für eine Bedeutung hat. Warum unterscheiden sich denn eigentlich die beiden Parameter Listen in dem Kommentar und in der Procedure?

*schaut mit dankendem gesichtsausdruck zum himmel hoch*
Hach.. ich bin dochnicht allein auf dieser großen weiten Welt...

Ich finde solche Header Kommentare etc immer dermaßen unübersichtlich... Ich weiß nich, wenn ich ne Procedure habe:


Was bringt mir es da, einen Header á la:


darüber zuschreiben...? *guckt verwirrt*
Das einzige was darin steht, was man nicht sowieso von der Procedure an sich erfährt ist Author + Datum... Datum interressiert mich i.d.R. relativ wenig. und Author... ICH schreibe meine Codes, und pflück mir die nich aus Proceduren von div. Leuten zusammen = es steht eh immer mein Name da = auch überflüssig

Das is meiner Meinung nach nur platzverschwendung und macht den Code unübersichtlich.

Genauso seh ich's mit normalen Kommentaren die immermal im Code sind...
Wenn man z.B. da wo man aus 6 Quads nen Würfel macht immer zu schreibt //Left Side etc.. das is ok, das mach ich auch...

Aber so dinge wie:


- Kein Kommentar -

und wieder halte ich fest an meiner überzeugung, das ich keine (extrem wenig) Kommentare in meine Codes schreibe. Und ich bin bestimmt nicht langsamer darin mich in einen 2 Jahre alten Quellcode von mir einzuarbeiten, als ihr die mit ihren Riesen kommentaren rumwerkeln. (evtl bin ich schneller, brauch ja keine ellenlangen texte lesen )

Au'revoir,
Aya~

PS: Und das Argument das für GruppenProjekte etc Kommentare überlebenswichtig sind... denke ich auchnicht unbedingt. Denn, wenn ich mir manchmal Progs runterlade um im Source zu gucken wie's ging etc... da sind dann meißt so unübersichtlich angeordnete und nichtsaussagende Kommentare drin, das die auch wieder nix bringen. Und ich find mich trotzdem jedesmal ohne große Probleme in fremden Source rein.

PPS: *Schutzschild vor sich errichtet* :rolleyes:

Also ich hatte die ganze zeit auch kaum kommentare gemacht, aber ich finde es schon übersichtlich... Ok, Autor macht kein sinn. Datum ist auch kacke wenn ich mirs recht überlege, wenn man viel an der procedure rumbastelt dann muss man immer das datum ändern... und das vergisst man schnell.

Ok, das mit den Parametern erklären wäre besser als einfach diese nochmal zu machen.
Und den Procedure Namen, brauch man au nich...

{-----------------------------------------------------------------------------
Parameter: Filename: Den Eindeutigen Dateinamen mit Verzeichnis, Bsp. 'C:\karte.map'
Aufgerufen von: TWorld.Create
Typ: Global
Beschreibung: Karte aus einer Datei laden
-----------------------------------------------------------------------------}
procedure LoadMap(FileName : String);

oder ganz übersichtlich wäre das hier:




Wie siehts aber aus mit Versionssnummern, was ist da sinnvoll ???
Das peil ich bis heute nich... wie ich Versionsnummern erhöhen muss/kann.
Es gibt die möglichkeit über Delphi, ja die Compilierungen zu erhöhen... automatisch... aber ich weiss nich... somit kann man ja nich sagen, ob man ne Alpha, Beta oder Finalversion hat.

Ich hab mir mal ne unit geschrieben, was mir Versionssnummer aus Start, End und änderungsdatum errechnet... funzt ganz gut... bloss sehen die versionsnummern, total unübersichtlich aus...

@Kommentare :
Wenn ich an einem Projekt für mich alleine Arbeite (es also z.B. nicht im Netz veröffentlichen will), dann mach ich Kommentare hauptsächlich nur der Übersichtlichkeit wegen um mich schneller im Quellcode orientieren zu können.Ich mach dann nen kurzen Kommentarblock beim Beginn einer neuen Klasse bzw. eines neuen Objektes und einen etwas kleineren Block beim Start einer Funktion bzw. Prozedur :

<!--pas--></span><table border='0' align='center' width='95%' cellpadding='3' cellspacing='1'><tr><td>Delphi-Source </td></tr><tr><td id='CODE'><!--pas1--><pre>// =============================================================================
// =============================================================================
// TBomberManGame
// =============================================================================
// =============================================================================

// =============================================================================
// TBomberManGame.InitOpenGL
// =============================================================================
<span class='reserved'>procedure</span> TBomberManGame.InitOpenGL(pColorDepth, pZDepth, pStencilDepth : Integer);
<span class='reserved'>begin</span>
[...]
<span class='reserved'>end</span>;</pre><!--pas2--></td></tr></table><span class='postcolor'><!--pas3-->

Das reicht im Normalfall, und die Dokumentation zu einzelnen Prozeduren und Funktionen kann ich mir eigentlich immer komplett sparen, da ich mit aussagekräftigen Variablen- und Prozedurnamen arbeite.Dann erklärt sich ja deren Funktion von selbst und macht die Kommentierung überflüssig.Wenn man für die Farbtiefe der GL-Initialisierung als Variablenname pColorDepth nimmt, dann sollte jeder direkt erkennen was damit gemeint ist.

@Versionsnummern :
Ich bezweifle das es da ne genormte Methode zur Ermittlung der Versionsnummern und des Versionsstatus gibt, und das Ganze in der Hand des Programmierers liegt.Ich halte mich ungefähr an folgendes Schema :
<span style='color:RED'>Techdemo</span> : Pre-Alpha, zeigt Technologien, die später im Spiel Verwendung finden und gibt dem Nutzer nen ersten Einblick in die Spielumgebung.
<span style='color:RED'>Alpha</span> : Im Gegensatz zur Techdemo sollten in einer Alpha bereits die meisten Spielelemente (und nen Großteil der finalen Spiellogik) enthalten und zumindest teilweise funktionsfähig sein.Sie dient dann zur Ermittlung der Hardwarekompatibilität und zu Feedbackzwecken bzgl. der Spielfeatures.
<span style='color:RED'>Beta</span> : Sie sollte alle Spielelemente in ihren finalen Formen enthalten und dient dan zum Balancing und weiteren Hardwarekompatibilitätstest.
<span style='color:RED'>Final</span> : Wie der Titel sagt sollte dies die fertige Version sein.Von nun an sollten neuere Versionen höchstens dann released werden, wenn diese schwerwiegenede Bugs beseitigen, Unterstützung für neue Hardware bieten, oder neue Features quasi als Bonus für Nutzer des Games mitbringen.

Das ist ungefähr dass, was ich mir unter den verschiedene Versionsstadien vorstelle.Das sich daran aber selbst viele kommerzielle Firmen nicht halten, sieht man z.B. an unfertigen Produkten wie Enter the Matrix, das innerhalb von einer Woche dann zweimal gepatcht werden muss und immer noch nicht richtig funzt...

_________________
www.SaschaWillems.de | GitHub | Twitter | GPU Datenbanken (Vulkan, GL, GLES)

Viel besser - aber natürlich musst du selbst wissen, was dir gefällt.
Header finde ich insofern sinnvoll, als sie eine visuelle Unterteilung in zusammengehörige Blöcke erlauben - so kann man etwa eine "große" globale Routine, die intern viele "lokale" Routinen aufruft zu einem Block zusammenfassen (weswegen die bei mir oft auch nur aus ///////////////////////////////// bestehen).

Ich würde Typ lokal/global auch weg lassen, da dies aus dem Kontext herauskommen sollte (also anstatt lokal lieber schreiben: intern von xxx verwendet), und was global ist, steht ja ohnehin im Interfaceteil - aber das ist wirklich Geschmackssache.

Besonders deine GenerateWorld gefällt mir gut - mit so einem Kommentar, weißt du auch nach fünf Jahren noch, was du eigentlich gemacht hast - ohne zehn Seiten Code mühevoll durchackern zu müssen.
Nur musst du auch berücksichtigen, dass du, wenn du so aufwendig kommentierst, auch dafür sorgen musst, dass die Kommentare bei allen Codeänderungen evtl. auch geändert werden müssen - sonst ist der ganze Nutzen wieder futsch.

Delphi aktualisiert übrigens automatisch die Buildnummer eines Programms, die du in den Projekteinstellungen zusammen mit diversen Kommentaren einstellen kann. Das nützt die aber nichts für die Sourceverwaltung. Dafür gibt es eigene Programme (wie etwa Visual SourceSafe) mit denen du Programmversionen ein- und auschecken kannst, sodass du immer auf einen bestimmten Stand zurückkehren kannst, wenn etwas ganz schief gelaufen ist.
Die sind aber auch umständlich und eigentlich nur für große Gruppen von Programmierern praktisch, die etwa übers Internet gemeinsam an einem Projekt arbeiten und ansonsten wenig persönlichen Kontakt haben

_________________
Viel Spaß beim Programmieren,
Mars
http://www.basegraph.com/

Ich meine man muss auch unterscheiden wofür ein Quellcode eigentlich ist.
Ist ein Quelltext für jemanden anders damit er daraus etwas lernen kann, dann müssen da Kommentare rein. Und einen riesigen Kommentar über einer Methode finde ich da etwas fehl am Platze. Da finde ich dann kleinere beschreibende Kommante, in den Quellen, viel sinnvoller. Evtl einen zusätzlichen Kommentar über der Methode der beschreibt was die Methode eigentlich tun sollte. Aber in einem Gut benannten Quellcode sollte das alleine schon durch den Namen erkennbar sein.

Sind die Quellen jetzt nur für mich, dann mache ich hauptsächlich nur an besonderen Stellen einen Kommentar. Also Dinge die ich NIE vergessen sollte und in dem zusammenhang lebenswichtig sind. Und wenn die Quellen einigermaßen gut strukturiert und sauber benannt wurden dann reicht das in 99% aller Fälle auch vollkommen aus.

Bei Quellen die ich nach außen reiche, da empfielt sich der Name (wer es gemacht hat), eine angabe über die Lizens (Freeware, etc) und eine History incl. Versionsnummer. Die Versionsnummer kann noch so erfunden sein es muss sich halt nachvolziehen lassen, welche Version ich hier habe und welche ich gerade einspielen will. Und da muss erkennbar sein, was sich überhaupt geändert hat. Damit ich mir das evtl. auch ersparen kann.

Aber im Endeffekt isses jedem seine Sache, was er da rein macht. Es werden eh nur Entwicker sehen und verstehen. Und die werdens vergessen.
Wenn es sich um eine große Sammlung von Funktionalitäten handelt, dann solltest du so oder so eine Dokumentation machen. In der musst (solltest) du dann eh etwas auf die einzelnen Klassen und Dateien eingehen.

ich mach kommentare normal wie aya oder lithander auch nur wenn notwendig, ich lass es mir aber nicht nehmen, über prozeduren oder funktionen solche blöcke:

<!--pas--></span><table border='0' align='center' width='95%' cellpadding='3' cellspacing='1'><tr><td>Delphi-Source </td></tr><tr><td id='CODE'><!--pas1--><pre>
<span class='comment'>(* ************************************************************************** *)</span>
{
funktionsname..
[beschreibung]
}
<span class='comment'>(* ************************************************************************** *)</span>
</pre><!--pas2--></td></tr></table><span class='postcolor'><!--pas3-->

zu setzen oder auch kleinere blöcke, je nach wichtigkeit der funktion. ne beschreibung kommt selten rein, nur wenn es zwingend notwendig ist und das net per // hinter ner zeile schnell und knapp erklärt werden kann.. weitergeben tu ich meine units sowieso nie, also kann ich mir sonstiges sparen

gruß
rochus

_________________
http://www.rochus.net