AGB  ·  Datenschutz  ·  Impressum  







Anmelden
Nützliche Links
Registrieren
Thema durchsuchen
Ansicht
Themen-Optionen

Quellcode Kommentieren

Ein Thema von franktron · begonnen am 5. Aug 2014 · letzter Beitrag vom 16. Aug 2014
Antwort Antwort
Seite 1 von 2  1 2      
Benutzerbild von sx2008
sx2008

Registriert seit: 15. Feb 2008
Ort: Baden-Württemberg
2.332 Beiträge
 
Delphi 2007 Professional
 
#1

AW: Quellcode Kommentieren

  Alt 5. Aug 2014, 19:09
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.
fork me on Github
  Mit Zitat antworten Zitat
Hansa

Registriert seit: 9. Jun 2002
Ort: Saarland
7.554 Beiträge
 
Delphi 8 Professional
 
#2

AW: Quellcode Kommentieren

  Alt 5. Aug 2014, 19:31
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 )
Gruß
Hansa
  Mit Zitat antworten Zitat
Benutzerbild von bernau
bernau

Registriert seit: 1. Dez 2004
Ort: Köln
1.312 Beiträge
 
Delphi 12 Athens
 
#3

AW: Quellcode Kommentieren

  Alt 5. Aug 2014, 20:47
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.
Gerd
Kölner Delphi Usergroup: http://wiki.delphitreff.de
  Mit Zitat antworten Zitat
Dejan Vu
(Gast)

n/a Beiträge
 
#4

AW: Quellcode Kommentieren

  Alt 5. Aug 2014, 21:16
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.
  Mit Zitat antworten Zitat
Benutzerbild von Chemiker
Chemiker

Registriert seit: 14. Aug 2005
1.859 Beiträge
 
Delphi 11 Alexandria
 
#5

AW: Quellcode Kommentieren

  Alt 5. Aug 2014, 22:18
Hallo,

also ich finde einen Kommentar nicht nutzlos.

Ich benutze Teilweise sehr alten ASM- und C/C++ -Code den ich selber mal vor 10-15 Jahren oder noch älter geschrieben habe und dank des Kommentars bin ich schnell in der Lage zu sehen wie ich die Routinen einsetzen kann und wie sie getestet worden sind.

Und sprechende Namen für Proceduren / Function sprechen heute, aber wie sprechen sie in 10 Jahren? Man ist nicht mehr im Thema und dann erscheint der Ablauf innerhalb der Procduren auch nicht mehr so klar das ist jedenfalls meine Erfahrung.

Bis bald Chemiker
wer gesund ist hat 1000 wünsche wer krank ist nur einen.
  Mit Zitat antworten Zitat
hoika

Registriert seit: 5. Jul 2006
Ort: Magdeburg
8.277 Beiträge
 
Delphi 10.4 Sydney
 
#6

AW: Quellcode Kommentieren

  Alt 6. Aug 2014, 06:59
Hallo,

auch ich bin der Meinung, dass JEDE Methode kommentiert sein muss.
Spätestens, wenn sich jemand in etwas einarbeiten soll, ist das wichtig.
Allerdings ist der Kommentar der Methode ein Sache,
weit wichtiger sind aber die Parameter- und Returnwertbeschreibung.
Ich halte mich übrigens an die Syntax von DelphiCode2Doc.

Bsp:

Delphi-Quellcode:
{*
  vergleicht 2 Strings, ohne Groß- und Kleinschreibung zu beachten

  @param  S1  erster String
  @param  S2  zweiter String
  @return  <1 S1<S2, >1 S1>S2, =0 S1=S2
}

function CompareText(const S1, S2: String): Integer;
Ich bin selber mal in die Falle getappt, dass ich auf -1 geprüft habe, statt auf <1

Dass man aus diesen Kommentaren auch schön eine Dokumentation rausziehen kann,
also die Code-Beschreibung nicht doppelt schreiben muss, ist ein angenehmer Zusatznutzen.


Heiko

Heiko
Heiko
  Mit Zitat antworten Zitat
Benutzerbild von himitsu
himitsu

Registriert seit: 11. Okt 2003
Ort: Elbflorenz
44.535 Beiträge
 
Delphi 12 Athens
 
#7

AW: Quellcode Kommentieren

  Alt 6. Aug 2014, 14:34
Hallo,

auch ich bin der Meinung, dass JEDE Methode kommentiert sein muss.
Spätestens, wenn sich jemand in etwas einarbeiten soll, ist das wichtig.
Allerdings ist der Kommentar der Methode ein Sache,
weit wichtiger sind aber die Parameter- und Returnwertbeschreibung.
Ich halte mich übrigens an die Syntax von DelphiCode2Doc.
Ich hab das die letzten Wochen auch mal bei einem Projekt gemacht, womit alleine das Unit-Interface von knapp 280 auf über 1800 Zeilen angewachsen ist, aber zum Glück kann man die sich Teile ausblenden zusammen falten lassen. (inzwischen über 3300 Zeilen, aber ich weiß jetzt nicht wie viel davon Code und wie viel Kommentare/Dokumentation sind)
Bsp:

Delphi-Quellcode:
{*
  vergleicht 2 Strings, ohne Groß- und Kleinschreibung zu beachten

  @param  S1  erster String
  @param  S2  zweiter String
  @return  <1 S1<S2, >1 S1>S2, =0 S1=S2
}

function CompareText(const S1, S2: String): Integer;
Ich bin selber mal in die Falle getappt, dass ich auf -1 geprüft habe, statt auf <1

Dass man aus diesen Kommentaren auch schön eine Dokumentation rausziehen kann,
also die Code-Beschreibung nicht doppelt schreiben muss, ist ein angenehmer Zusatznutzen.
PS: Es gibt dafür auch Konstanten, welche man verwenden könnte.
Delphi-Quellcode:
type
  TValueRelationship = -1..1;

const
  LessThanValue = Low(TValueRelationship);
  EqualsValue = 0;
  GreaterThanValue = High(TValueRelationship);

Mit DelphiCode2Doc nimmst du dir aber eine nette Funktion weg, welche es seit 2005/2006 im Delphi gibt.
=> Help-Insight

Unbenannt.jpg Und Delphi kann das inzwischen (XE2/XE3) selber zusammenfalten, ohne daß man die Regionen dafür benötigt.

Zitat:
Ach, und natürlich benötigt man richtiges Werkzeug. Ich bin auf C# umgestiegen und arbeite mit Resharper, da kann man sehr viel Refactoring ratzfatz schnell durchziehen. Codeschnipsel markieren => Methode extrahieren => Parameter benennen => fertig. Geht so -glaube ich- nicht in Delphi, oder?
Doch. (teilweise)

Refactoring > Methode Extrahieren
uvm., auch von Fremdanbietern (GExperts, cnPack, ...)
Ein Therapeut entspricht 1024 Gigapeut.

Geändert von himitsu ( 6. Aug 2014 um 14:48 Uhr)
  Mit Zitat antworten Zitat
mkinzler
(Moderator)

Registriert seit: 9. Dez 2005
Ort: Heilbronn
39.880 Beiträge
 
Delphi 11 Alexandria
 
#8

AW: Quellcode Kommentieren

  Alt 6. Aug 2014, 07:14
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.
Was dann auch eine Form von Dokumentation/Kommentierung wäre.

Zitat:
Und sprechende Namen für Proceduren / Function sprechen heute, aber wie sprechen sie in 10 Jahren? Man ist nicht mehr im Thema und dann erscheint der Ablauf innerhalb der Procduren auch nicht mehr so klar das ist jedenfalls meine Erfahrung.
Aber wenn der Kommentar eine bloße Wiederholung des Funktionnamens ist, würde diese Dier dann genausowenig helfen.
Markus Kinzler
  Mit Zitat antworten Zitat
Dejan Vu
(Gast)

n/a Beiträge
 
#9

AW: Quellcode Kommentieren

  Alt 6. Aug 2014, 07:33
Was dann auch eine Form von Dokumentation/Kommentierung wäre.
Die Frage ist ja nicht, ob man grundsätzlich dokumentieren sollte (überflüssige Frage), sondern ob man *im* Quellcode dokumentieren sollte. Jedenfalls hab ich das so interpretiert.

Wir haben z.B. unsere API mit 1-2 Sätzen im Code dokumentiert und sehr ausführlich im internen Wiki. Die Code-Dokumentation dient (in VS) dazu, beim Code-Proposal gleich was sehen zu können, auch wenn die Kommentare z.T. echt überflüssig sind, denn sowohl Methoden- als auch Parameternamen sind selbsterklärend. Man erkennt zwar, das eine Exception geworfen wird (kein Rückgabewert), aber trotzdem ist es besser, man sieht es in der Code-Dokumentation der Methode.

Das hat imho nichts damit zu tun, den Code durch Kommentare verständlicher machen zu wollen, denn das geht eigentlich immer schief und ist der falsche Weg.

Zitat:
Und sprechende Namen für Proceduren / Function sprechen heute, aber wie sprechen sie in 10 Jahren?
Na, Englisch bleibt Englisch.
Zitat:
...und dann erscheint der Ablauf innerhalb der Prozeduren auch nicht mehr so klar das ist jedenfalls meine Erfahrung.
Dann sind deine Methoden vielleicht noch zu lang.

Eine Methode besteht bei mir neben Zuweisungen und Methodenaufrufen aus entweder einer Schleife oder einem if-Statement, wobei ich selbst hier noch awäge, ob die Kontrollstruktur nicht doch in eine eigene Methode kommt. In jedem Fall löst die Methode genau eine Aufgabe, die sich im Namen wiederspiegelt. Verschachtelungstiefe maximal 2-4, wobei das Abstraktionsniveau gleich bleibt. Das verstehe ich auch noch nach 10 Jahren (und ich mach das seit 30), denn der Code ist -bis auf die unterste Ebene, ausschließlich englisch. Grammatikalisch nicht immer 100% korrekt, aber verständlich.

Ich muss ja nicht den gesamten Code, also bis zur untersten Stufe sehen. Es reicht doch, wenn ich verstehe, was die Methode macht:

Delphi-Quellcode:
Function ConvertBytesToHexString (const bytes : TByteArray) : String;
Begin
  Result := '';
  foreach byte in bytes do
    Result := Result + Convert.ToHex(byte);
End;
Das versteht jeder auch nach 50 Jahren noch. Wie genau ein Byte in ein 'Hex' konvertiert wird, ist ja schnurz. Ich weiß, was ein Byte ist, ich weiß, was ein 'Hex' ist. Ich weiß, was 'Convert' bedeutet.

Beim Coden stelle ich mir immer die Frage:"Was für ein Gesicht macht mein Kollege, wenn er meinen Code liest?" und "Würde ich anfangen, zu stottern oder zu rudern, wenn ich ihm meinen Code erklären müsste?". Denn das muss ich, wenn er Schrott ist. Da ich meine Ruhe haben will, mach es lieber gleich so, das alles vorbildlich ist. Mäckeln tun die dann immer noch (liegt wohl in der Natur des Programmierers)x, aber dann auf sehr hohem Niveau: "Sollte die Methode nicht 'ConvertByteArrayToHexString' heißen? oder (hier) "Die Methode ist an der falschen Stelle: Verschiebe sie als statische Methode in unseren Converter". So macht programmieren Spaß, denn man pusht sich gegenseitig immer höher.
  Mit Zitat antworten Zitat
mkinzler
(Moderator)

Registriert seit: 9. Dez 2005
Ort: Heilbronn
39.880 Beiträge
 
Delphi 11 Alexandria
 
#10

AW: Quellcode Kommentieren

  Alt 6. Aug 2014, 08:36
Zitat:
Die Frage ist ja nicht, ob man grundsätzlich dokumentieren sollte (überflüssige Frage), sondern ob man *im* Quellcode dokumentieren sollte. Jedenfalls hab ich das so interpretiert.
Manchmal hat man nur den Quellcode als Dokumentation (nicht wirklich zu empfehlen), bzw. die Kommentare werden automatisiert in eine Dokumentation überführt. Zudem ist es imho schon sinnvoll mögliche Problemfelden bzw. Besonderheiten direkt im Code zu dokumentieren.
Markus Kinzler
  Mit Zitat antworten Zitat
Antwort Antwort
Seite 1 von 2  1 2      


Forumregeln

Es ist dir nicht erlaubt, neue Themen zu verfassen.
Es ist dir nicht erlaubt, auf Beiträge zu antworten.
Es ist dir nicht erlaubt, Anhänge hochzuladen.
Es ist dir nicht erlaubt, deine Beiträge zu bearbeiten.

BB-Code ist an.
Smileys sind an.
[IMG] Code ist an.
HTML-Code ist aus.
Trackbacks are an
Pingbacks are an
Refbacks are aus

Gehe zu:

Impressum · AGB · Datenschutz · Nach oben
Alle Zeitangaben in WEZ +1. Es ist jetzt 14:15 Uhr.
Powered by vBulletin® Copyright ©2000 - 2025, Jelsoft Enterprises Ltd.
LinkBacks Enabled by vBSEO © 2011, Crawlability, Inc.
Delphi-PRAXiS (c) 2002 - 2023 by Daniel R. Wolf, 2024-2025 by Thomas Breitkreuz