Kommentare

Nicht-ausführbare Hinweise

Jede ernstzunehmende Programmiersprache bietet eine Möglichkeit zum Anbringen von Kommentaren. Hier finden sie eine kurze Übersicht. Oft vernachlässigt, jedoch ebenso wichtig: Kommentare in Konfigurations-Dateien.
Entwicklung Ausgewählte Kapitel zur Programmierung
Kommentare Anmerkungen und Tipps
Versionen Ganze Zeilen, Teil-Zeilen, Blöcke
Programmiersprachen C++, CSS, Fortran, HTML, Java, Javascript, Pascal, Perl, PHP, Postscript, Python, Shell, SQL, TeΧ, VBA, Win-Konsole, XML, ...
Konfiguration Kommentare in Konfigurations-(Text)-Dateien

Kommentare

Wozu Kommentare ?

Kommentare sind Anmerkungen in einem Klartext, z.B. im Quelltext von Programmen oder in Konfigurations-Dateien.
Die streng wissenschaftliche Bezeichnung für einen Kommentar lautet 'Annotation'

● Gute Produkte sind ausführlich und sorgfältig dokumentiert.
● Ein guter Kommentar erklärt die nicht offensichtlichen Details von Programmen - für andere Menschen, aber auch für die/den EntwicklerIn selbst.
● Der Quelltext größerer Programme ist ohne Kommentare praktisch wertlos.
● Gute Doku ist einigermaßen verständlich. Leider überwiegen in der Praxis die Negativ-Beispiele: Man versteht die spärliche Doku nur dann, wenn man sich mit dem Programm selbst bereits auskennt.

● Ein oft vernachlässigtes Gebiet ist die Doku von ↓ Konfigurations-Dateien: Bei Stress (d.h. meistens) wird oft darauf verzichtet. Wenn ein Programm oder Server dann Probleme macht, gibt es oft kein Zurück mehr: Das gesamte Programm muss abgeschaltet, de-installiert, neu installiert und von Anfang an nochmals konfiguriert werden...

Ergänzen statt Überschreiben

Man muss 'Das Rad nicht ständig neu erfinden': Jede/r EntwicklerIn verwendet Code-Teile aus anderen Programmen, Büchern oder aus dem Internet.
Allerdings muss man den Original-Code meist für den eigenen Bedarf modifizieren.
♣ In diesem Fall ist es klug, den Original-Text nicht zu löschen oder zu überschreiben, sonden mit Kommentar abzuschalten.
Das ist umso wichtiger, je weniger man das Original durchschaut...

Zeichen-Code

● Professioneller Kommentar-Text enthält ausschließlich → ASCII-Zeichen, am besten nur Buchstaben, Ziffern und Leerzeichen.

● Da Kommentar-Text bei der Verarbeitung ignoriert wird, ist man versucht, darin auch Sonderzeichen zu verwenden (z.B. deutsche Umlaute ÄÖÜäöüß ). Davon wird dringend abgeraten - Vermeiden sie in Kommentaren auch die Zeichen !#$%*<>? die in manchen Programmen besondere Bedeutung haben.

● Bei Verwendung von Zeichen mit Code>127 besteht Gefahr, dass irgendein Programm diese Zeichen falsch interpretiert - besonders bei Weitergabe des Quelltextes an andere Betriebssysteme, Gebiete anderer Sprachen, - d.h. immer bei Upload ins Internet.
Auch → Unicode-Zeichen im Quelltext sind ein unkalkulierbares Risiko, selbst bei Deklaration als → UTF-Code:
Alle über ASCII hinausgehenden Zeichen werden am besten maskiert.

♣ Tipp: Wenn man in Kommentaren keine Sonderzeichen verwendet, dann kann man den Quelltext eigener Programme und Webseiten automatisch auf Zeichen mit ASCII-Code>127 durchsuchen lassen: Alle derartigen Fehler werden gefunden und können leicht beseitigt werden.

Sprache

• Es ist international üblich, für Kommentare einfaches Englisch zu verwenden.
• In Lokal-Sprache werden nur Programme ohne Bedeutung kommentiert. Eine Ausnahme sind Programme zu Lehr-Zwecken.
• Kauderwelsch wie z.B. Hacker-Slang ist nur für den Verfasser lustig.
Englisch-Kenntnisse sind für EntwicklerInnen unentbehrlich. Wichtige Originale werden fast auschließlich in Englisch verfasst, lokale Sprach-Versionen leider oft von ÜbersetzerInnen hergestellt, die keine Ahnung von der Materie haben...

Mehrfach-Interpreter

Die Erstellung von Programmen wird immer mehr automatisiert.
Das bedeutet: Programme schreiben andere Programme.

In diesem Fall muss man im Quelltext auf die Syntax und insbesondere auf die Kommentar-Regeln aller Komponenten und auf die Reihenfolge der Anwendung Rücksicht nehmen.
Bekannte Beispiele sind die Herstellung von HTML- oder Javascript-Code (dynamische Webseiten) mit Java, Perl, PHP, Python...

Die Erkennungs-Zeichen für 'fremde' Interpreter wie z.B.
<?php ?>
innerhalb von HTML-Code haben einige Ähnlichkeit mit Kommentaren.

Anweisungen fremder Programme

Alle zur Automatisierung der Software-Herstellung dienenden Programme müssen ihre Anweisungen in den Quelltext anderer Programmiersprachen einbetten - normalerweise in Kommentare.

Besondere Zeichen-Kombinationen innerhalb der Kommentare dienen als Erkennungs-Zeichen für derartige Anweisungen von Frend-Programmen.
Das meist verwendete Beispiel sind Web-Editor Programme, die ihre Anweisungen in HTML-Kommentare einbetten, z.B.
<!-- InstanceBeginEditable name="title" -->

<!-- InstanceEndEditable -->
In diesem Fall muss man bei m Anlegen eigener Kommentare darauf achten, nicht irrtümlich Anweisungen des Web-Editors auszulösen.

Kommentar-Varianten

Ganze Zeilen

Jede Programmiersprache und jede Konfigurations-Datei bietet die Möglichkeit, in einer eigenen Zeile einen kurzen Text zu hinterlassen.
Dazu beginnt eine Zeile mit einem oder mehreren Zeichen besonderer Bedeutung. Die gesamte Zeile gilt als Kommentar und wird bei der Interpretation des Textes ignoriert.
● Diese Version bietet die größte Sicherheit und sollte immer bevorzugt werden.
Solche Kommentare lassen sich auch automatisch einfügen, sowie mit Hilfs-Programmen leicht finden und analysieren.

Teil-Zeilen

Oft ist es möglich, die gleichen Zeichen wie bei ganz-zeiligen Kommentaren auch an einer beliebigen Stelle einer Zeile einzufügen. In diesem Fall wird der erste Teil der Zeile interpretiert, der zweite Teil wird als Kommentar ignoriert.
Diese Version erlaubt etwas kompakteren Code, ist jedoch schwieriger automatisch zu finden und zu verarbeiten. Verzichten sie nach Möglichkeit darauf und verwenden sie ganz-zeilige Kommentare.

Kommentar-Blöcke

Viele Programmiersprachen bieten die Möglichkeit, größere Kommentar-Bereiche lediglich durch die Markierung von Anfang und Ende zu definieren. Nur in diesem Fall dürfen sich Kommentare auch über mehrere Zeilen erstrecken.
Das spart viel Arbeit, sollte jedoch ausschließlich zum Debuggen reserviert werden:
● Mit dieser Methode ist es möglich, rasch einen beliebig großen Teil des Quelltextes rasch abzuschalten ('aus-kommentieren').
• Das funktioniert allerdings nur dann, wenn 'echte' Kommentare ausschließlich zeilenweise markiert wurden.
● Ansonsten erzeugt man irrtümlich mehrfache, miteinander kollidierende Kommentar-Blöcke: Die Entwirrung kostet viel unnötige Zeit...

Kommentar-Dateien

Im Quelltext sollte nur direkter Kommentar zu den enthaltenen Anweisungen enthalten sein. Größere Kommentare zu anderen Zwecken, z.B. Installation, Konfiguration, Anwendung, Beispiele, etc. sind besser in eigenen Text-Dateien enthalten.
Erfahrungsgemäß werden solche Dateien (readme...) von der Zielgruppe nicht gelesen. Man kann sie jedoch im Internet anbieten: Dort werden sie gesucht, gefunden und manchmal sogar gelesen.

Programmiersprachen und Verwandte

C++

Die Zeichen // beginnen einen Kommentar, der bis zum Zeilen-Ende reicht.
// Das ist ein C++-Kommentar
a=123; // halbzeiliger Kommentar
Die Zeichen /* beginnen einen Kommentar-Block, der auch mehrzeilig sein kann.
Die Zeichen */ beenden den Kommentar-Block.
/* Das ist ein C++-Kommentar */
Ein häufiger Sonderfall ist der Preprozessor:
Seine Anweisungen sind im Quelltext enthalten und beginnen mit dem # Zeichen, z.B.
#define array_size 100
#ifdef array_size
int array_a[array_size];
#endif
Diese Anweisungen steuern den Preprozessor-Programm, werden von diesem entfernt und gelangen nicht bis eigentlichen C++-Compiler.

CSS (Cascading StyleSheets)

Die Zeichen /* beginnen einen Kommentar-Block, der auch mehrzeilig sein kann.
Die Zeichen */ beenden den Kommentar-Block.
/* Das ist ein CSS-Kommentar */
Ein häufig auftretender Spezialfall ist die Einbettung eines CSS-<style>-Elements in HTML- oder XML-Code:
<style type="text/css" media="screen">
/* <![CDATA[ */
body{color:#00F;}
/* ]]> */
</style>
XML ↓ verlangt die Begrenzung fremder Code-Elemente durch <![CDATA[ ... ]]>
Damit CSS diese Zeichen ignoriert, werden sie in CSS-Kommentare verpackt.

Fortran

Die Zeichen C oder * am Zeilen-Anfang (1. Spalte) bezeichnen eine Kommentar-Zeile.
C     Das ist ein Fortran-Kommentar
Fortran wurde früher in Technik und Naturwissenschaften viel verwendet.
Noch heute gibt es erstklassige Funktions-Bibliotheken in Fortran, die man teilweise in andere Programmiersprachen (z.B. Perl) integrieren kann.

HTML

Die Zeichen <!-- beginnen einen Kommentar-Block, der auch mehrzeilig sein kann.
Die Zeichen --> beenden den Kommentar-Block.
<!-- Das ist ein HTML-Kommentar -->
HTML-(Web)-Editoren und andere Automatisierungs-Programme verwenden HTML-Kommentare für eigene Anweisungen, z.B.
<!-- InstanceBeginEditable name="title" -->
<!-- InstanceEndEditable -->

Java und Javascript

Die Zeichen // beginnen einen Kommentar, der bis zum Zeilen-Ende reicht.
// Das ist ein Java(script)-Kommentar
var a=123; // halbzeiliger Kommentar
Die Zeichen /* beginnen einen Kommentar-Block, der auch mehrzeilig sein kann.
Die Zeichen */ beenden den Kommentar-Block.
/* Das ist ein Java(script)-Kommentar */
Ein häufig auftretender Spezialfall ist die Einbettung eines <script>-Elements in HTML- oder XML-Code:
<script type="text/javascript">
// <![CDATA[
alert("Javascript");
// ]]>
</script>
XML ↓ verlangt die Begrenzung fremder Code-Elemente durch
<![CDATA[ ... ]]>
Damit Javascript diese Zeichen ignoriert, werden sie in JS-Kommentare verpackt.

Pascal

Je nach Compiler- oder Interpreter (TurboPascal)-Variante scherint es mehrere Möglichkeiten für Kommentare zu geben. Pascal hat derzeit kaum mehr Bedeutung und wurde von modernen Programmiersprachen abgelöst.
Die Zeichen // beginnen einen Kommentar, der bis zum Zeilen-Ende reicht:
// Das ist ein Pascal-Kommentar
Die Zeichen (* oder { beginnen einen Kommentar-Block, der auch mehrzeilig sein kann.
Die Zeichen *) oder } beenden den Kommentar-Block.
(* Das ist ein Pascal-Kommentar *)
{ Das ist ein Pascal-Kommentar }

Perl

Das Zeichen # beginnt einen Kommentar, der bis zum Zeilen-Ende reicht.
# Das ist ein Perl-Kommentar
$a=123; # halbzeiliger Kommentar

PHP

Die Zeichen // beginnen einen Kommentar, der bis zum Zeilen-Ende reicht.
// Das ist ein PHP-Kommentar
$a=123; // halbzeiliger Kommentar

Die Zeichen /* beginnen einen Kommentar-Block, der auch mehrzeilig sein kann.
Die Zeichen */ beenden den Kommentar-Block.
/* Das ist ein PHP-Kommentar */
PHP-Code wird oft in Webseiten eingebettet, z.B.
<?php print "Hier ist PHP"; ?>
Als Zeichen zum Start des PHP-Interpreters werden je nach Konfiguration auch die Zeichen <? anerkannt. Das kann Kollisionen ergeben, z.B. mit der → XML-Deklaration (in jeder mit PHP hergestellten → XHTML-Webseite):
<?xml version="1.0" encoding="utf-8" ?>
In diesem Fall muss man die XML-Deklaration aus dem XHTML-Code entfernen - am besten indem man sie in den PHP-Code integriert, z.B. so
<?php
$x='<?xml version="1.0" encoding="utf-8"?>';
print "$x\n";
?>

Postscript

bezeichnet einen Standard für Satz-Programme (Layout)
Das Zeichen % beginnt einen Kommentar, der bis zum Zeilen-Ende reicht.
% Das ist ein Postscript-Kommentar
Ganz ähnlich wird allerdings die erste Zeile jedes Postscript-Programms formuliert:
%!PS-Adobe-1.0
sowie Postscript Struktur-Informationen, z.B.
%%Title: Titel

Python

Das Zeichen # beginnt einen Kommentar, der bis zum Zeilen-Ende reicht.
# Das ist ein Python-Kommentar
a=123 # halbzeiliger Kommentar

Shell-Konsole (Linux, Cygwin)

Das Zeichen # beginnt einen Kommentar, der bis zum Zeilen-Ende reicht.
# Das ist ein Shell-Kommentar
a=123 # halbzeiliger Kommentar

SQL

Die Zeichen /* beginnen einen Kommentar-Block, der auch mehrzeilig sein kann.
Die Zeichen */ beenden den Kommentar-Block.
/* Das ist ein SQL-Kommentar */
In direkt (manuell oder mit Programmen) erteilten SQL-Befehlen werden natürlich keine Kommentare verwendet.
Allerdings kann man Sequenzen von SQL-Anweisungen in Text-Dateien (meist *.sql) zusammenstellen und zur gemeinsamen 'Batch'-Verarbeitung verwenden. In diesem Fall sind Kommentare hilfreich.

TeΧ und LaTeΧ

(Das Χ ist ein griechisches Chi, man spricht 'Tech') bezeichnet ein Satz-Programm (Layout), welches vorwiegend im mathematischen, technischen und naturwissenschaftlichen Bereich verwendet wird.
Das Zeichen % beginnt einen Kommentar, der bis zum Zeilen-Ende reicht.
% Das ist ein TeΧ-Kommentar

VBA

Kommentar-Zeilen (und Teil-Zeilen) beginnen mit einem ' (single quote) Zeichen.
' das ist ein VBA-Kommentar

Windows-Konsole (cmd.exe)

Die Zeichen rem oder :: beginnen einen Kommentar, der bis zum Zeilen-Ende reicht. Windows Konsolen-Befehle unterscheiden normalerweise nicht zwischen Groß- und Kleinbuchstaben
REM Das ist ein Kommentar
Rem Das ist ein Kommentar
rem Das ist ein Kommentar
:: Das ist ein Kommentar

XML

XML umfasst die gesamte Familie moderner "Auszeichnungs-Programme", z.B. MathML, → SVG, → XHTML (diese Webseite), → XSL, ...
Zu dieser Familie gehören auch Daten wie z.B. OpenDocument (OpenOffice) oder OpenXML (M$Word docx), deren Dateien zusätzlich ZIP-komprimiert sind.
Die Zeichen <!-- beginnen einen Kommentar-Block, der auch mehrzeilig sein kann.
Die Zeichen --> beenden den Kommentar-Block.
<!-- Das ist ein XML-Kommentar -->
Ein häufig auftretender Spezialfall ist die Einbettung fremder Code-Elemente (z.B. ↑ CSS , ↑ Javascript) in XML-Code:

● Die Zeichen <![CDATA[ bezeichnen den Beginn von Fremd-Code, die Zeichen ]]> dessen Ende.

Diese XML-Zeichen müssen vor dem fremden Interpreter geschützt werden, deshalb werden sie zusätzlich in einen Kommentar der jeweiligen Programmiersprache verpackt. 		Ein anderer häufiger Fall ist die Herstellung eines XML-Dokuments (z.B. einer XHTML-Webseite) mit ↑ PHP: In diesem Fall muss man verhindern, dass die XML-Deklaration
<?xml version="1.0" encoding="utf-8" ?>
irrtümlich den PHP-Interpreter auslöst. Das wird erreicht, wenn man die Deklaration aus dem XML-Quelltext entfernt und in den PHP-Quelltext verlagert:
<?php
$x='<?xml version="1.0" encoding="utf-8"?>';
print "$x\n";
?>

Konfigurations-Dateien
Auf Linux erfolgt die Konfiguration in den meisten Fällen über Text-Dateien. Das trifft auf das Betriebssystem ebenso zu wie auf fast alle Server-Programme, die meisten Bibliotheken, usw.

Das bietet viele Vorteile, z.B.
• Die (menschliche) Kontrolle ist wesentlich einfacher - man braucht dazu keine speziellen Programme, jeder Text-Editor genügt.
• Die Automation ist einfach und transparent: Man kann Text-Konfigurations-Dateien mit Programmen lesen, ändern oder erstellen.

Diese Technik ist zwar einfach anwendbar, aber trotzdem sicher: Das Linux Betriebssystem verwaltet einen besonders strengen Zugriffs-Schutz.

● Eine wichtige Konsequenz: Linux Konfigurations-Dateien können und sollten unbedingt kommentiert werden. 		Microsoft verfolgt in den meisten Fällen die gegenteilige Strategie:

Konfiguration-Daten werden so gut wie möglich versteckt, nach Möglichkeit jedem Zugriff entzogen und binär verschlüsselt. Auf Vista sind viele wichtige Details selbst für den Administrator nicht oder nur mit aufwändigen Tricks zugänglich - Eine Art von Selbst-Entmündigung, vor der auch ein legaler Kauf der Lizenz nicht schützt.

Die Registry-Datenbank ist das klassische Ungetüm aller Windows-Systeme: Binär codiert, im System versteckt, nur mit besonderen Programmen (z.B. regedit.exe) zugänglich, ...
In diesem Fall erübrigt sich ein Kommentar.

● Auch auf Windows-Systemen gibt es einige Ausnahmen: Programme, die aus der Linux-Welt portiert wurden, sind meist ebenso wie auf ihrer Heimat mit Text-Dateien transparent zu konfigurieren, z.B. der Apache Webserver oder die Programmiersprache PHP.
In Gebrauch sind wenige Varianten, die meist miteinander kompatibel sind:

Die Zeichen # oder ; beginnen einen Kommentar, der bis zum Zeilen-Ende reicht.

Am besten hält man sich an die Syntax der fast immer vorhandenen Original-Dokumentation.
Halbzeilige Kommentare sind zwar oft zulässig, sollten jedoch vermieden werden.

♣ Tipp: Beachten sie auch hier die Regel, in Kommentaren nur ASCII-Zeichen zu verwenden, keinesfalls Sonderzeichen (Umlaute). 		♣ Tipp: Überschreiben sie niemals den Original-Text: Schalten sie ihn mit einem Kommentar-Zeichen ab und schreiben sie den geänderten Text darunter.
♣ Tipp: Bezeichnen sie jede Änderung mit ihrem Namen oder eindeutigen Zeichen. So finden sie die Änderungen auch in sehr langen Konfigurations-Dateien.

Beispiel (z.B. Apache Webserver)
Original-Text:
DocumentRoot "/srv/www/htdocs"

Nach Änderung:
# Original:
# DocumentRoot "/srv/www/htdocs"
# Aenderung durch Mayer:
DocumentRoot "/home/apache/htdocs"
# Ende der Aenderung
Auf Linux ist es üblich, Konfigurations-Dateien durch Script-Programme automatisch zu erstellen.
Lesen sie die Dokumentation - insbesondere diejenige innerhalb der zu ändernden Datei - vor einer Änderung:
Es kann passieren, dass die Datei bei System-Start, spätestens jedoch beim nächsten System- oder Software-Update durch ein Script-Programm überschrieben wird. 		Zum Schutz individueller Konfigurations-Anweisungen wurde die Konfiguration von Programmen in allen neueren Linux Distributionen in System-Teile und User-Teile getrennt. Die User-Teile werden nach den System-Teilen geladen und überschreiben bzw. ergänzen diese allenfalls.

Das erscheint anfangs kompliziert, bietet jedoch ausgezeichneten Komfort für die Administration: Die User-Teile der Konfiguration bleiben von den Script-Programmen unangetastet.

Zum Inhaltsverzeichnis Homepage von PS-Trainer   >   Entwicklung   >   Kommentar