www.mikrocontroller.net

Forum: PC-Programmierung Kommentarzeilen mit "." abschließen?


Announcement: there is an English version of this forum on EmbDev.net. Posts you create there will be displayed on Mikrocontroller.net and EmbDev.net.
Autor: Guido C. (guidoanalog)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Hallo,

eine Frage, die ich mir schön des Öfteren gestellt habe ist die, ob man 
Kommentare im Quellcode mit einem "." abschließen soll. Bisher halte ich 
es so, dass ich kurze Kommentare wie z. B. "Variable initialisieren" 
ohne Punkt am Ende und längere Kommentare wie z. B. "Hier erfolgt die 
Entflechtung des gordischen Knotens." mit einem Punkt abschließe. 
Allerdings meine ich einmal in einem Softwaretechnikbuch gelesen zu 
haben, dass Kommentare grundsätzlich ohne Satzzeichen am Ende 
geschrieben werden. Wie seht bzw. handhabt Ihr das?

Mit freundlichen Grüßen
Guido

Autor: Stefan May (smay4finger)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Wenn Du das Softwaretechnikbuch noch findest, dann schmeiß es weg.

Im Allgemeinen sind Kommentare kontraproduktiv. Wozu soll ich denn einen 
Kommentar "Variable initialisieren" hinschreiben, wenn es doch schon im 
Quellcode so dasteht?

   int a = 2; // Variable initialisieren

Was soll denn der Kommentar verdeutlichen? Kommentieren kannst Du 
Design-Entscheidungen. Beispiel:

   List foo = new MySuperDuperList(); // wegen Effizienz

mfg, Stefan.

Autor: Sven P. (haku) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Schön, dass sich auch mal jemand ästhetischen Aspekten widmet :-)

Ich benutze zunächst immer die mehrzeiligen Kommentarzeichen /* */, auch 
für Einzeiler. Sieht sauberer aus; insbesondere schreibe ich keine 
Kommentare zusammen mit Quelltext in eine Zeile.

Bei Einzeilern lasse ich dann den Punkt weg, beginne aber in 
Großschreibung. Mehrzeiler formuliere ich in ganzen Sätzen, dann 
natürlich mit Punkt.

Etwas dazwischen bedeutet, dass ich den Quelltext überdenken muss und 
vermutlich wieder Blödsinn programmiert habe...

Autor: Joachim Drechsel (Firma: JDCC) (scheppertreiber)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Sven P. schrieb:
> Schön, dass sich auch mal jemand ästhetischen Aspekten widmet :-)

Ja.

Aber ich hätte gerne bei C auch das kurz-knapp-und-platzsparende ;
am Anfang einer Zeile. Irgendwie wirkt das am natürlichsten.

Kommentare nur für's Grobe, der Code sollte sich selbst erklären.
Platzsparende Notation mit Einrückungen (wegen der überbordenden
Geschwätzigkeit hatte ich mal Pascal in die Tonne getreten).

Autor: Karl Heinz (kbuchegg) (Moderator)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Exakt: Code sollte sich nach Möglichkeit selbst kommentieren.

Abgesehen davon bin ich schon froh, wenn ich in Kommentaren nicht 
allzuviele Tippfehler habe. Über die Frage 'Punkt oder kein Punkt' hab 
ich mir ehrlich gesagt noch nie Gedanken gemacht. Kommentare sind für 
mich Entwurfsnotizen und keine literarischen Meisterwerke.

Autor: tritratroll (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
If you can say it with code code it, else comment it. <-- mit Punkt ;-)

Autor: Joachim Drechsel (Firma: JDCC) (scheppertreiber)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Ich habe auch mal in einem Anfall von Wahn erst das Handbuch/Doku
geschrieben und dann erst das Programm. Irgendwie ein interessantes
Experiment ... Kommentare ? => Handbuch :)

Wie gesagt: Einmal. :-)))

Autor: Wissender (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Von unseren Rechnungsprüfern (BWLer) werde ich nach "number of lines of 
code" bezahlt.
Seither schreibe ich Kommentare überwiegend senkrecht.

Autor: Joachim Drechsel (Firma: JDCC) (scheppertreiber)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Wissender schrieb:
> Seither schreibe ich Kommentare überwiegend senkrecht.

Ein verunglückter Blocksatz bringt auch Zeilen ...

Autor: Guido C. (guidoanalog)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Hallo,

den Code so zu schreiben, dass man ihn möglichst ohne Kommentare 
verstehen kann ist natürlich auch mein Anliegen ;-)

Ich finde es jedoch recht angenehm, wenn man anhand der Kommentare sieht 
wo was im Programm passiert. Wenn ein Quelltext sehr lang ist und ich 
nach 5-6 Jahre etwas anpassen muss finde ich es recht praktisch bereits 
beim Überfliegen des Quelltextes zu sehen was wo passiert.

Sven P. schrieb:
> insbesondere schreibe ich keine
> Kommentare zusammen mit Quelltext in eine Zeile.

Irgendwie mag auch ich keine Kommentare, die in der gleichen Zeile wie 
der Quelltext stehen. Warum kann ich so genau nicht sagen. Vermutlich, 
weil der Kommentar immer "nervt", wenn man die betreffende Zeile 
editiert.

Karl Heinz Buchegger schrieb:
> Kommentare sind für
> mich Entwurfsnotizen und keine literarischen Meisterwerke.

Da hast Du sicher recht. Wenn ich weiß, dass der Quellcode nur für meine 
Augen bestimmt ist sehe ich das mit den Kommentaren auch recht locker. 
Doch oft ist es so, dass andere Personen meinen Quellcode lesen oder gar 
anpassen.

Wie ich sehe scheint meine bisherige Vorgehensweise (s. o.) nicht allzu 
"abwegig". Ich werde wohl dabei bleiben.

Vielen Dank für Eure Beiträge.

Mit freundlichen Grüßen
Guido

Autor: Vlad Tepesch (vlad_tepesch)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Sven P. schrieb:
> Ich benutze zunächst immer die mehrzeiligen Kommentarzeichen /* */, auch
> für Einzeiler. Sieht sauberer aus; insbesondere schreibe ich keine
> Kommentare zusammen mit Quelltext in eine Zeile.

tja so unterscheiden sich die geschmäcker.

Ich finde Kommentare zwischen den Codezeilen stören den Lesefluss.
Ich schreibe lieber in eine zweite Spalte neben den Code, zumindest wenn 
es sich um relativ kurzen Erklärungen zu dem nebenstehenden Code 
handelt.

wenn allerdings der nachfolgende Block kommentiert wird. zb mit 
ausführlicheren Verfahrensbeschreibungen oder um zu zeigen, dass ein 
neuer Schritt beginnt (dewn man allerdings eventuell in eine eigene 
Funktion auslagert), dann auch zwischen die Code Zeilen

Autor: Stefan May (smay4finger)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Guido C. schrieb:
> Ich finde es jedoch recht angenehm, wenn man anhand der Kommentare sieht
> wo was im Programm passiert. Wenn ein Quelltext sehr lang ist und ich
> nach 5-6 Jahre etwas anpassen muss finde ich es recht praktisch bereits
> beim Überfliegen des Quelltextes zu sehen was wo passiert.

Was im Programm passiert musst Du anhand des Quelltext verstehen. Meist 
ist es doch so, dass Kommentare etwas beschreiben, was schon lange nicht 
mehr da ist. Deshalb: Wenn der Quelltext zu lang ist, um ihn zu 
verstehen, dann refaktorisiere ihn.

Lies doch mal, was Martin Fowler zu dem Thema sagt:

  http://martinfowler.com/bliki/CodeAsDocumentation.html

mfg, Stefan.

Autor: ingo (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Mittlerweile hat sich, auch durch das mittlerweile vorherschende 
Bildschirmformat (Briefkastenschlitz), die Notwendigkeit ergeben, die 
Kommentare, hinter den Code zu schreiben.
Hinweis: dieser Text kann Spuren von Sarkasmus enthalten.
mfG ingo

Autor: Sven P. (haku) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Vlad Tepesch schrieb:
> Ich finde Kommentare zwischen den Codezeilen stören den Lesefluss.
> Ich schreibe lieber in eine zweite Spalte neben den Code, zumindest wenn
> es sich um relativ kurzen Erklärungen zu dem nebenstehenden Code
> handelt.
Das meinte ich weiter oben. Wenn die wirklich den Lesefluss stören, dann 
sind es meistens zu viele und/oder fehlplazierte. Also Zeit für 
Refaktorisierung...

Bei Assembler schreib ich die Kommentare ja auch hinter die Zeilen, aber 
bei C und Ähnlichem mag ich kurze, knappe, selbstredende Zeilen. Und ein 
Kommentar, der da wirklich noch hinter den Quelltext in eine Zeile 
passt, kann nur schwer noch sinnvoll sein.

Autor: Joachim Drechsel (Firma: JDCC) (scheppertreiber)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Ach ja: Sinnvoll ist das bei Änderungen. Das schreibe ich mir mit
Datum und Grund mit hinein.

Autor: Vlad Tepesch (vlad_tepesch)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Joachim Drechsel schrieb:
> Ach ja: Sinnvoll ist das bei Änderungen. Das schreibe ich mir mit
> Datum und Grund mit hinein.

Für das Tracking von Änderungen ist das VCS zuständig

Autor: Georg A. (georga)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Schlimmer als das Design der Kommentare finde ich die im 
"professionellen" Umfeld (zB. Intel...) grassierende "wir schreiben 
erstmal 300 Zeilen Copyright, Lizenz, Rechtshilfebelehrung, 
etc."-Methode. Aber dann keine einzige Zeile, was die Codewüste 
eigentlich machen soll :( Manchmal kann man es nur noch am Filenamen 
erraten...

Autor: Lomann (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
ingo schrieb:
> Hinweis: dieser Text kann Spuren von Sarkasmus enthalten.

Muss so etwas denn sein? :(

Autor: Rufus Τ. Firefly (rufus) (Moderator) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Vlad Tepesch schrieb:
> Für das Tracking von Änderungen ist das VCS zuständig

Und das kann einem auch sagen, warum ausgerechnet diese eine Zeile in 
diesem Modul geändert wurde?

Autor: Rolf Magnus (rmagnus)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Rufus Τ. Firefly schrieb:
> Vlad Tepesch schrieb:
>> Für das Tracking von Änderungen ist das VCS zuständig

100% Ack.

> Und das kann einem auch sagen, warum ausgerechnet diese eine Zeile in
> diesem Modul geändert wurde?

Ja. Das hat man nämlich in die Commit-Message geschrieben. Die muß sich 
dabei auch gar nicht mal speziell auf genau eine bestimmte Zeile 
beziehen, sondern kann sich auch auf mehrere auf verschiedene Dateien 
verteilte Zeilen beziehen, die alle gemeinsam zu einer Änderung (z.B. 
einem Bugfix) gehören. Und man kann auch gleich noch auf einen Blick 
sehen, was dafür alles geändert wurde und wie es davor ausgesehen hat.
Das alles zusammen gibt deutlich mehr Aufschluß, als eine Zeile 
Kommentar.

Autor: Roland (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Real Programmers don't need comments-- the code is obvious.

Autor: Joachim Drechsel (Firma: JDCC) (scheppertreiber)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Rolf Magnus schrieb:
> 100% Ack.

Da bin ich eher Kreativer wie Verwalter.

Autor: Rolf Magnus (rmagnus)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Joachim Drechsel schrieb:
> Da bin ich eher Kreativer wie Verwalter.

Das muß doch kein Hinderungsgrund sein. Der einzige Unterschied ist, daß 
du bei dem hier:

Joachim Drechsel schrieb:
> Ach ja: Sinnvoll ist das bei Änderungen. Das schreibe ich mir mit
> Datum und Grund mit hinein.

einen Commit machst und den Grund in die Commit-Message schreibst.

Antwort schreiben

Die Angabe einer E-Mail-Adresse ist freiwillig. Wenn Sie automatisch per E-Mail über Antworten auf Ihren Beitrag informiert werden möchten, melden Sie sich bitte an.

Wichtige Regeln - erst lesen, dann posten!

  • Groß- und Kleinschreibung verwenden
  • Längeren Sourcecode nicht im Text einfügen, sondern als Dateianhang

Formatierung (mehr Informationen...)

  • [c]C-Code[/c]
  • [avrasm]AVR-Assembler-Code[/avrasm]
  • [code]Code in anderen Sprachen, ASCII-Zeichnungen[/code]
  • [math]Formel in LaTeX-Syntax[/math]
  • [[Titel]] - Link zu Artikel




Bitte das JPG-Format nur für Fotos und Scans verwenden!
Zeichnungen und Screenshots im PNG- oder
GIF-Format hochladen. Siehe Bildformate.
Hinweis: der ursprüngliche Beitrag ist mehr als 6 Monate alt.
Bitte hier nur auf die ursprüngliche Frage antworten,
für neue Fragen einen neuen Beitrag erstellen.

Mit dem Abschicken bestätigst du, die Nutzungsbedingungen anzuerkennen.