AGB  ·  Datenschutz  ·  Impressum  







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

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 2  1 2      
Benutzerbild von sakura
sakura

Registriert seit: 10. Jun 2002
Ort: Unterhaching
11.420 Beiträge
 
Delphi 12 Athens
 
#1

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 13: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...

......
Lizbeth 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.165 Beiträge
 
Delphi 10.3 Rio
 
#2

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 13: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
 
#3

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14: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
Benutzerbild von Sherlock
Sherlock

Registriert seit: 10. Jan 2006
Ort: Offenbach
3.821 Beiträge
 
Delphi 12 Athens
 
#4

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14:14
Tja, selbsterklärender Code ist das hohe Ziel der Entwicklerschaft.

Allein, er ist es leider nur für ungefähr eine Woche. Darum gilt: Es gibt keinen selbsterklärenden Code. Jeder ist der Meinung super Code zu produzieren, der sogar in aller Regel tut was er soll. Nur wird dieser Code von Menschen mit unterschiedlichem Kenntnisstand sehr unterschiedlich wahrgenommen (vulgo: verstanden). Darum schreibe ich zumindest was der folgende Code tun soll. Das hilft beim schnellen Überfliegen ungemein, man muss nämlich nicht erst compilieren, sondern kann sich auf die Prosa verlassen. Und nein, ich schreibe keine Kommentare für writeln('Hello World') .

Sherlock
Oliver
Geändert von Sherlock (Morgen um 16:78 Uhr) Grund: Weil ich es kann
  Mit Zitat antworten Zitat
SProske

Registriert seit: 16. Feb 2015
Ort: Halle/S.
116 Beiträge
 
Delphi 10.2 Tokyo Enterprise
 
#5

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14:55
Ergänzend zu bisher genannten Punkten
- Berechnungsformeln (Herleitung, Leselinks etc.)
- Codeschnipsel die aus dem Web übernommen oder hergeleitet wurden
- Wenn ich irgendwo beim Debuggen ewig hing, versuche ich meine Erkentnisse zu dokumentieren (Refaktoring wäre natürlich besser, aber wann hat man shcon mal Zeit...)
- wenn Code für irgendwelche Sonderfälle angepasst werden musste -> Doku für diesen Sonderfall
Sebastian
  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, 15:05
Wenn ich diesen Thread so lese, überkommt mich das Gefühl, dass für viele Leute "Kommentar" und "Dokumentation" das selbe zu sein scheint. Das finde ich interessant
Ohne hier jetzt irgendwie werten zu wollen, war mir das nicht bewusst, dass scheinbar viele Leute in diesem Aspekt nicht unterschieden.
Jens
  Mit Zitat antworten Zitat
Benutzerbild von Sherlock
Sherlock

Registriert seit: 10. Jan 2006
Ort: Offenbach
3.821 Beiträge
 
Delphi 12 Athens
 
#7

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 15:17
Wenn ich diesen Thread so lese, überkommt mich das Gefühl, dass für viele Leute "Kommentar" und "Dokumentation" das selbe zu sein scheint. Das finde ich interessant
Ohne hier jetzt irgendwie werten zu wollen, war mir das nicht bewusst, dass scheinbar viele Leute in diesem Aspekt nicht unterschieden.
Die Grenzen verschwimmen, wenn man ein Tool verwendet, daß aus dem Code die Dokumentation erzeugen soll.

Sherlock
Oliver
Geändert von Sherlock (Morgen um 16:78 Uhr) Grund: Weil ich es kann
  Mit Zitat antworten Zitat
Benutzerbild von himitsu
himitsu

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

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 15:14
Jupp, Quellangaben von Fremdcodes, sind auch immer gut, wenn sie vor Ort dokumentiert sind. (nicht nur wegend der Lizenz, sondern auch für zukünftige Updates und Bugfixe)
Ein Therapeut entspricht 1024 Gigapeut.
  Mit Zitat antworten Zitat
Delphi-Laie

Registriert seit: 25. Nov 2005
1.474 Beiträge
 
Delphi 10.1 Berlin Starter
 
#9

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14:18
Ja, auch meine Wenigkeit ist in dieser Hinsicht eher ein ziemlicher, aber kein absoluter Faulpelz.

In dem Augenblick, in dem man den Code schreibt, ist einem der Grund dafür klar, das Kommentieren daher (erstmal) unnötig.

Man muß also zwei Hürden überwinden:

1. Man muß sich in diesem Augenblick (oder unmittelbar danach) bewußt werden, daß es ggf. mal wieder etwas zu kommentieren gibt.
2. Man muß entscheiden, ob und inwieweit der Code "selbsterklärend" ist - oder eben nicht. Das ist schwierig einzuschätzen, weil man selbst sein schlechtester Korrekturleser ist.

Oft wird diese Faulheit bestraft, indem man sich Tage bis Jahre später dann auch erst wieder mehr oder minder mühsam in seinen eigenen Code, zumindest Teile davon, meistens ziemlich mühsam hineindenken muß. Klar, man hat dabei einen Heimvorteil, der aber mit der Zeit schwindet.
  Mit Zitat antworten Zitat
Benutzerbild von himitsu
himitsu

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

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 14:29
Bei API-Wrappern versuche ich mich grade an einer Dokumentation durch Attribute, wo z.B. DLL, wichtigste Exports und nötige Berechtigungen genannt werden.
Aktuell haben sie keinerlei Funktion, könnten aber in Zukunft ausgelesen werden.

ALLERDINGS geh ich da etwas vom Standard weg ... meine Attribute gelten auch für ALLES Nachfolgende, ab der Definition, innerhalb der Definitionsebene und nicht nur für die EINE Nachfolgende Methode/Typ.
=> nur das Nötigste und nicht alles mit Attributen vollgekleistert, sonst erkennt man den Code ja nicht mehr. (ich hätte mir Postfix-Attribute gewünscht ... wie ein //-Kommentar, hinter die CodeZeile)
Ein Therapeut entspricht 1024 Gigapeut.

Geändert von himitsu ( 4. Okt 2016 um 14:31 Uhr)
  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 05:38 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