AGB  ·  Datenschutz  ·  Impressum  







Anmelden
Nützliche Links
Registrieren
Zurück Delphi-PRAXiS Programmierung allgemein Programmieren allgemein Wie und wieviel kommentiert Ihr Euren Code

Wie und wieviel kommentiert Ihr Euren Code

Ein Thema von v2afrank · begonnen am 4. Okt 2016 · letzter Beitrag vom 12. Okt 2016
Antwort Antwort
Seite 1 von 4  1 23     Letzte » 
v2afrank

Registriert seit: 9. Mai 2005
Ort: Bocholt
538 Beiträge
 
Delphi XE2 Professional
 
#1

Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 13:49
Hallo,
wir haben ein Projekt an ein externes Softwareunternehmen vergeben und ich habe jetzt von denen den ersten Code bekommen.
Was mir aufgefallen ist, ist die Menge an Kommentaren, die fast gleich 0 ist. Laut Clean Code sollte das ja wohl auch der empfohlene Weg sein. Wir haben hier bei uns in der Firma selber Regeln aufgelegt wie Unitköpfe und Funktionen dokumentiert und kommentiert werden sollen. Jetzt interessiert mich einfach mal wie Ihr das so handhabt. Haltet Ihr Euch eher an das CleanCode Prinzip oder ???
  Mit Zitat antworten Zitat
Benutzerbild von Valle
Valle

Registriert seit: 26. Dez 2005
Ort: Karlsruhe
1.223 Beiträge
 
#2

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 13:57
Ich kommentiere relativ wenig. Methoden, deren Zweck nicht unmittelbar ersichtlich ist, werden im Code dokumentiert. Codestellen, die unerwartetes oder unverständliches tun auch. Ansonsten versuche ich den Code so zu schreiben dass er sprechend ist und nicht kommentiert werden muss.
Valentin Voigt
BOFH excuse #423: „It's not RFC-822 compliant.“
Mein total langweiliger Blog
  Mit Zitat antworten Zitat
Benutzerbild von haentschman
haentschman

Registriert seit: 24. Okt 2006
Ort: Seifhennersdorf / Sachsen
4.797 Beiträge
 
Delphi 10.1 Berlin Professional
 
#3

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14:09
Moin...

[meine Meinung]
Ich halte die Kommentare bezüglich der History (Unitkopf, Procedurekopf) für überflüssig. Wenn man ein Versionskontrolsystem hat ist das doppelte Arbeit. Desweiteren sind sprechende Procedurnamen / Parameternamen das A + O. Da erübrigt sich meistens ein Kommentar. Persönlich sortiere ich meine Proceduren nach dem Typ... (...Eventhandler, Work, GUI Events, Actions etc.) Andere Suchen mit den Hilfsmitteln über den QT. Ich mag einfach keine Unordnung...
Wichtig allerdings ist das Kommentieren von Prozeduren bezüglich der Funktionsweise von Blöcken / einzelnen Zeilen z.B. wenn es notwendig erscheint.

...Also ich kommentiere dann nur wenn notwendig.
[/meine Meinung]

@Valle: +1

Geändert von haentschman ( 4. Okt 2016 um 14:14 Uhr)
  Mit Zitat antworten Zitat
Benutzerbild von himitsu
himitsu
Online

Registriert seit: 11. Okt 2003
Ort: Elbflorenz
38.588 Beiträge
 
Delphi 10.4 Sydney
 
#4

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14:11
Da alle meine Codes selbsterklärend und leicht verständlich sind, hab ich natürlich keinelei Kommentare im Code.



Spaß bei Seite.
Ich führe meine Dokumentation im Code, also sind mindestens an vielen Funktionen/Typen/Konstanten (im Interface) entsprechende PasDoc XMLDoc (Documentation Insight) und ich führe das aktuell auch für UnitHeader ein.

Im Code wird vorallem "schlecht" Erkennbares, sowie "komisches" und abweichendes Verhalten kommentiert, sowie "böse" Codeoptimierungen, wo ich den OriginalCode dahinter schreib, damit man versteht was gemacht wird.


Zitat:
Ich halte die Kommentare bezüglich der History (Unitkopf, Procedurekopf) für überflüssig
Historie mach ich auch nicht.

Bei Komponenten-Units steht im Kopf das zugehörige Projekt, sowie die Copyright/Lizenz (nur der Name und das Detailierte als Link)

Bei Prozeduren mach ich auch nicht mehr überall die Dokumentation dran (hatte ich mal angefangen, aber lass ich grade wieder von ab) ... Jupp, sprechende Bezeichner sind immer besser, aber machmal muß man einfach bissl was erklären.
Garbage Collector ... Delphianer erzeugen keinen Müll, also brauchen sie auch keinen Müllsucher.
Delphi-Tage 2005-2014

Geändert von himitsu ( 4. Okt 2016 um 14:16 Uhr)
  Mit Zitat antworten Zitat
Der schöne Günther

Registriert seit: 6. Mär 2013
5.716 Beiträge
 
Delphi 10 Seattle Enterprise
 
#5

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14:15
Ich habe nichts neues beizutragen, nur eine Frage in der Richtung:

Ich habe nie verstanden was es bringt eine Unit selbst zu kommentieren. Angenommen sie enthält entweder
  1. Eine Klasse
  2. Ein Interface und ein dazugehöriger Exception-Typ
  3. Einen Haufen Nummern-Konstanten

Was sollte der Text in den ersten Zeilen der Unit einem erzählen können was man nicht auf den ersten Blick sieht?
  Mit Zitat antworten Zitat
Benutzerbild von Nersgatt
Nersgatt

Registriert seit: 12. Sep 2008
Ort: Emlichheim
693 Beiträge
 
Delphi 10.1 Berlin Professional
 
#6

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14:17
Ich mach es wie Valle. Mein Code ist wenig bis gar nicht Kommentiert. Nur, wenn es wirklich schwer zu durchschauende Stellen sind. Und die versuche ich soweit es geht zu vermeiden. In diese Vermeidung investiere ich durchaus auch einige Zeit.

Wenn die Fremdfirma die Funktionsköpfe etc. nach euren Regeln kommentieren soll, dann müsste das entsprechend im Vertrag geregelt werden.
Jens
  Mit Zitat antworten Zitat
Benutzerbild von sakura
sakura

Registriert seit: 10. Jun 2002
Ort: München
11.579 Beiträge
 
Delphi 10.4 Sydney
 
#7

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14:51
Ich kann nicht verstehen, wenn jemand nicht oder nur wenig kommentiert.

Wie oben schon angemerkt, für zumindest protected und public/published Members und alles im Interface-Bereich, sollte man immer dokumentieren, damit die Nutzer dieser Schnittstellen in der Doku das gewünschte Verhalten sofort verstehen können. Dafür eignet sich natürlich XMLDoc-Styles.

Gerade wenn mehrere an einem Projekt arbeiten ist dieses unabdingbar. Natürlich kann man vieles leicht erkennen, wenn man sich den Quelltext anschaut, aber das kostet immer wieder Zeit, jedes Mal. Die Methoden kurz zu dokumentieren kostet nur einmal Zeit

Innerhalb von Methoden eignet es sich vor dem Erstellen des eigentlichen Codes in PDL (programm description language) kurz die gewünschte Logik zu schreiben und dann den Code zu schreiben. Das erleichtert das spätere Korrigieren von Fehlern in Logik und Implementierung ungemein.

Alles andere erachte ich inzwischen als wahrlich schlechten Stil, und davon habe ich genug hier vor mir

Insgesamt sollte die Dokumentation von Codes nicht im Wege stehen, sondern helfen. Insbesondere, wenn jemand anders mal am Code arbeiten muss. Selbst hundert leichte Methoden in einer Unit sind nur schwer zu verstehen, wenn man gar keine Marschrichtung kennt...

......
Daniel W.
Ich bin nicht zurück, ich tue nur so
  Mit Zitat antworten Zitat
Benutzerbild von Mavarik
Mavarik

Registriert seit: 9. Feb 2006
Ort: Stolberg (Rhld)
4.024 Beiträge
 
Delphi 10.3 Rio
 
#8

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14:53
Kommentare nur wenn der Code nicht auf den 1. Blick zeigt was Sache ist.

oder auch gerne mal Kommentare wie:

// Frank lass hier die Finger weg, Du hast schon 3x versucht das zu optimieren - es bringt nix...

Mavarik
  Mit Zitat antworten Zitat
Benutzerbild von Mavarik
Mavarik

Registriert seit: 9. Feb 2006
Ort: Stolberg (Rhld)
4.024 Beiträge
 
Delphi 10.3 Rio
 
#9

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14:54

Wie oben schon angemerkt, für zumindest protected und public/published Members und alles im Interface-Bereich, sollte man immer dokumentieren, damit die Nutzer dieser Schnittstellen in der Doku das gewünschte Verhalten sofort verstehen können. Dafür eignet sich natürlich XMLDoc-Styles.
Was ein Interface macht sollte man erkennen. Wichtiger finde ich es, welche möglichen Exceptions auftreten können.
  Mit Zitat antworten Zitat
Benutzerbild von JasonDX
JasonDX
(CodeLib-Manager)

Registriert seit: 5. Aug 2004
Ort: München
1.062 Beiträge
 
#10

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 15:05
Ich versuche mich prinzipiell daran zu orientieren:
Der Code erklärt selbst, was er macht. Kommentare ergänzen das Warum wenn erforderlich.

Im Bezug auf Dokumentation von Methoden und Klassen: Klassen haben bei mir seltenst Dokumentation; Methoden dokumentiere ich dann, wenn sie außerhalb der Klasse sichtbar sind. Dabei konzentriere ich mich auf Grenzfälle, Exceptions und nicht zwingend intuitive Verhaltensweisen.
Mike
Passion is no replacement for reason
  Mit Zitat antworten Zitat
Themen-Optionen Thema durchsuchen
Thema durchsuchen:

Erweiterte Suche
Ansicht

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 +2. Es ist jetzt 19:55 Uhr.
Powered by vBulletin® Copyright ©2000 - 2021, Jelsoft Enterprises Ltd.
LinkBacks Enabled by vBSEO © 2011, Crawlability, Inc.
Delphi-PRAXiS (c) 2002 - 2021 by Daniel R. Wolf