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 2 von 4     12 34   
Benutzerbild von Sherlock
Sherlock

Registriert seit: 10. Jan 2006
Ort: Offenbach
3.553 Beiträge
 
Delphi 10.3 Rio
 
#11

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 15: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
Geändert von Sherlock (Morgen um 16:78 Uhr) Grund: Weil ich es kann
  Mit Zitat antworten Zitat
Delphi-Laie

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

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 15: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.
Sortierkino und Sortier-Kino
Ob ein Programm wirklich gute Qualität hat, erkennt man am besten dann, wenn man einen unbedarften darauf losläßt.
  Mit Zitat antworten Zitat
Benutzerbild von himitsu
himitsu
Online

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

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 15: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)
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 15:31 Uhr)
  Mit Zitat antworten Zitat
Lemmy

Registriert seit: 8. Jun 2002
Ort: Berglen
2.293 Beiträge
 
Delphi 10.3 Rio
 
#14

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 15:32
ich notiere mir die Verbindung zu externen Dokumenten wie Pflichtenheft / Anforderungskatalog, damit ich zum einen nachlesen kann warum der Code so ist wie er ist (hoffentlich) und zum anderen bei Änderungen an der Anforderung die relevanten Codestellen schnell finde.

Ansonsten dokumentiere ich dann, wenn ich denke, dass der folgende Code "unerwartet" ist - man könnte vermutlich auch sagen, dass solcher Code "riecht".

Als Ausnahme natürlich Interfaces wenn diese als Bibliothek auch anderen zur Verfügung gestellt werden, dann muss das per XMLDoc/Documentation Insight dokumentiert sein...
  Mit Zitat antworten Zitat
SProske

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

AW: Wie und wieviel kommentiert Ihr Euren Code

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

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 16: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 himitsu
himitsu
Online

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

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 16: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)
Garbage Collector ... Delphianer erzeugen keinen Müll, also brauchen sie auch keinen Müllsucher.
Delphi-Tage 2005-2014
  Mit Zitat antworten Zitat
Benutzerbild von Sherlock
Sherlock

Registriert seit: 10. Jan 2006
Ort: Offenbach
3.553 Beiträge
 
Delphi 10.3 Rio
 
#18

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 16: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
Geändert von Sherlock (Morgen um 16:78 Uhr) Grund: Weil ich es kann
  Mit Zitat antworten Zitat
Aviator

Registriert seit: 3. Jun 2010
1.588 Beiträge
 
Delphi 10.3 Rio
 
#19

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 16:38
In neuen Programmen versuche ich im Interface Abschnitt die Methoden mit Hilfe von XML Dokumentation zu beschreiben. Auch die Parameter. Nichts desto trotz verwende ich sprechende Parameternamen um nicht immer wieder nachlesen zu müssen. Aber auch damit andere eine Methode aufrufen bzw. begutachten können wenn ich den Code weitergeben müsste.

Bei alten Projekten versuche ich neue Methoden immer etwas zu beschreiben. Die stechen dann zwar oft heraus weil sonst nix anderes Dokumentiert ist, aber immerhin besser als nichts.

Kommentare verwende ich im Code ebenfalls wenn bestimmte Stellen sehr komplex sind und es einfach nicht besser/übersichtlicher zu programmieren ist.

Schlimm finde ich aber so Kommentare wie das bei Linux in manchen Konfigurationsdateien zu finden ist. Da wird erst 100 Zeilen Kommentar geschrieben und dann kommt die eigentlich eine (!) Zeile die eine Funktion hat. Das übersieht man dann einfach und wundert sich, wieso nix in der Datei drin steht was etwas bewirken könnte.
  Mit Zitat antworten Zitat
Benutzerbild von p80286
p80286

Registriert seit: 28. Apr 2008
Ort: Stolberg (Rhl)
6.658 Beiträge
 
Delphi 7 Personal
 
#20

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 16:46
Wenn alles so läuft wie gedacht, bracht man keine Kommentare.
(Und die Erde ist eine Scheibe)

Bei der Durchsicht von alten Code-Friedhöfen ist mir aufgefallen wieviel Kontext für das Verständnis notwendig ist, und der fehlt nach ein paar Jahren. Es ist nicht selbstverständlich, daß MWSF=11; einen Mehrwertsteuerfaktor meint. Und wenn ein GetCaseKey heute noch sprechend ist, weil die Datenbank ein Feld CaseKey hat, dann ist das Morgen ein GetCaseID . Gut man könnte auch GetCasePK nutzen, aber was wenn es sich nicht um den PK handelt??

Gruß
K-H
Programme gehorchen nicht Deinen Absichten sondern Deinen Anweisungen
R.E.D retired error detector
  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 20:42 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