Mein Delphi-Style

[Mithrandir]

Zitat:

Zitat von jbg

Zitat:

Zitat von Daniel G

aber bei EMBC

OT: EMBC kürzt sich mit EMBT (T wie Technologies) ab ;-)

Danke,

wusste nicht, dass es da was offizielles gibt. ;) Ich war grad nur zu faul, den Namen auszuschreiben. :mrgreen: Vielleicht eine Idee für die Akronym-Liste. :)

[stoxx]

mal auch eine andere Frage, ich habe mir schon länger und immer mal wieder vorgenommen, vor jeder Funktion eine eindeutige Erklärung zu schreiben, sowas in der Art.
Schafft ihr das durchzuhalten? die Mühe ist es sicherlich wert, aber bei kleinen Funktionen lässt man es dann und irgendwann steht vielleicht oft nur noch kurz da, was die Funktion macht, sonst nix ...

(das ist jetzt mal ein Beispiel aus einem C Quelltext, den ich aber gut fand)

Delphi-Quellcode:

{==============================================================================
*   Function:        BYTE isShort (char aChar, BYTE mode)
*
*   PreCondition:    None
*
*   Input:           aChar   - The char to be checked
*                    mode    - if TRUE, '*' is allowed
*
*   Output:          0       - The character is acceptable
*                    1       - The char is a lower case letter
*                    2       - Unacceptable char
*                    3       - A space character
*
*   Side Effects:    None
*
*   Overview:        Checks to see if a char is acceptable in short format
*
*   Note:            None
==============================================================================}

[quendolineDD]

Selten. Aber gerade wenn deine Sachen viele verschiedene Leute benutzen sollen und direkt mit dem Code in Berühungen kommen, ist es hilfreich Verwendung, Parameter und Ausgabe zu erklären. Finde das, wie bei JEDi gemacht ganz gut, nur dann werden halt die Deklarationen der Klassen ewig lang. Und schlussletztlich werden alle Einträge dann extrahiert und dokumentiert.

[Luckie]

Viel zu lang. Das bläht den Quelltext unnötig auf und macht in insgesamt unübersichtlicher.

Delphi-Quellcode:

Function:        BYTE isShort (char aChar, BYTE mode)

Überflüssug, der Funktionsname steht im Quelltext.

Delphi-Quellcode:

Input:           aChar   - The char to be checked
*                    mode    - if TRUE, '*' is allowed

Umbenennen der Parameter macht den Kommentar überflüssig: CharToCheck, AllowWildCards.

Delphi-Quellcode:

Output:          0       - The character is acceptable
*                    1       - The char is a lower case letter
*                    2       - Unacceptable char
*                    3       - A space character

Verwendetman einen Aufzählungsdatentyp mit sprechenden bezeichnung, ist auch dies überflüssig.

Delphi-Quellcode:

Overview:        Checks to see if a char is acceptable in short format

Bessere bennnung der Funktion macht auch dies überflüssig.

[mkinzler]

Imho schadet etwas Doku des Quellcodes nicht.

[Die Muhkuh]

Zitat:

Zitat von mkinzler

Imho schadet etwas Doku des Quellcodes nicht.

Das ist richtig, aber nur an Stellen, an denen es von Nöten ist.

Michael hat schön demonstriert, dass man bei simpler Umbenennung eine riesen Wurst an Kommentare wegwerfen kann. (Clean Code lässt grüßen, nicht wahr, Michael? :zwinker: ).

[p80286]

Zitat:

Zitat von Luckie

Delphi-Quellcode:

Input:           aChar   - The char to be checked
*                    mode    - if TRUE, '*' is allowed

Umbenennen der Parameter macht den Kommentar überflüssig: CharToCheck, AllowWildCards.

Da muß dann aber auch gleich die Erläuterung, welche Wildcards gemeint sind, dazu kommen.
So wird nur ein Zeichen zur "Wildcard" erklärt.

Zitat:

Zitat von Luckie

Delphi-Quellcode:

Output:          0       - The character is acceptable
*                    1       - The char is a lower case letter
*                    2       - Unacceptable char
*                    3       - A space character

Verwendetman einen Aufzählungsdatentyp mit sprechenden bezeichnung, ist auch dies überflüssig.

Delphi-Quellcode:

Overview:        Checks to see if a char is acceptable in short format

Bessere bennnung der Funktion macht auch dies überflüssig.

Wenn ich mich richtig erinnere, basiert das Beispiel auf einem C-Quelltext und da ist es mit den Aufzählungstypen wohl nicht so weit her. Zumindestens in älteren Programmen ist das wohl eine reine Pascal-Errungenschaft.

Im Prinzip finde ich so einen "Header" ganz gut weil:
ein "Sprachfremder" findet sich besser zurecht, weil er im Klartext erfährt was sich in der Funktion versteckt.
wenn man einen solchen "Header" erstellt, dann ist man gezwungen sich ein paar Gedanken über die erwünschte Funktionalität zu machen, da fallen oft irgendwelche Schludereien auf.

Gruß
K-H

[R2009]

Hi Luckie,

du kommst mir etwas vor wie ein Praktikant, den wir vor langer Zeit hatten.
Er hatte die Aufgabe ein Visualisierungstool für unsere Zähler zu proggen.
Am letzten Tag, kurz bevor er verschwand, wurde er gefragt wo denn die Doku zu dem Teil sei.
Antwort:
Das Programm erklärt sich von selbst.
Ausserdem braucht ihr keine Doku, das Programm läuft und ist fehlerfrei.

Jetzt im ernst:
Keine Zeile Kommentar im Quellcode ist zuviel! Aussagekräftige Prozedurnamen sind was schönes aber wer
von uns neigt nicht dazu aus: zwei_Zeichen_in_string_einfuegen zw_zei_str zu machen und das ist dann nicht mehr lesbar.

Viele Grüsse!

[Fridolin Walther]

Stimme auch hier mit Luckie überein. Ausserdem sind Kommentare so etwas ganz spezielles. Ich persönlich vermeide sie wenn möglich. Es gibt nichts schlimmeres als falsche oder "outdated" Kommentare. Darüber hinaus sind sie, bei korrekter Benennung der Funktion und Parameter einfach überflüssig. Statt "Mache ein foo für alle bar in der Liste" steht halt einfach "Mache ein foo für alle bar in der Liste" in der Syntax der Sprache da ;). Von daher sehe ich die Notwendigkeit zu kommentieren als erstes Anzeichen für schlecht verständlichen und somit in den meisten Fällen auch wartbaren Code an. Wobei ich natürlich auch komplexere Konstrukte, die auf den ersten Blick evtl. nicht direkt zu durchschauen sind, mit einem entsprechenden Kommentar versehe, wenn sich die Komplexität anders nicht vermeiden lässt. Ausserdem wird Code, den ich für Leute in Boards schreibe, meist exzessiv kommentiert, weil ich keine Ahnung hab was die Leute können ;).

Zitat:

Zitat von R2009

Jetzt im ernst:
Keine Zeile Kommentar im Quellcode ist zuviel!

Doch diese besagten Kommentare "Diese Funktion bekommt einen Char Pointer übergeben." sind einfach nur überflüssig.

Zitat:

Zitat von R2009

Aussagekräftige Prozedurnamen sind was schönes aber wer von uns neigt nicht dazu aus: zwei_Zeichen_in_string_einfuegen zw_zei_str zu machen und das ist dann nicht mehr lesbar.

Ich neige nicht dazu. Und jeder der in unserem Team dazu neigt, neigt nicht lange dazu oder darf sich auf dem Arbeitsmarkt andere Herausforderungen suchen ;). Ansonsten gehört eine Doku natürlich dazu. Darüber brauchen wir uns ja nicht zu unterhalten.

[DeddyH]

Kommentare sind IMHO gerade in Foren sinnvoll, wenn man nicht klarmachen will, was man tut, sondern wie man es tut. Nicht jeder kann schließlich auf Anhieb meinen teils wirren Gedankengängen folgen :zwinker: