Kommentare im Quelltext

Kommentieren sollte beim Programmieren oder Scripten viel häufiger vorkommen. Erinnert es den Teampartner doch an kommende Baustellen oder gegenteilig funktionell Beendetes – kennzeichnet andererseits auch zum Verständnis. Hier ein lustiger Kommentar aus der bekannten WordPress wp-config.php-Datei:

/* That's all, stop editing! Happy blogging. */

Infos geben, Sicherheit erzeugen

In einer Konfigurationsdatei wird vieles geändert oder ergänzt. Höchste Zeit, dieses vor Ort mit einem Kommentar zu dokumentieren. Hier ein sinnvolles Beispiel aus der oben genannten WordPress-Config:

/* keine Sicherungen von Versionen - ein Original in der DB und gut */
define('WP_POST_REVISIONS', 1);
define('EMPTY_TRASH_DAYS', 5 ); // Empty trash every 5 days

Hier erkennt man auch die verschiedenen Arten, zu kommentieren. Innerhalb einer Zeile wird in /* eingeschlossen, nur für eine Zeile reichen zwei Slashes: // Das gilt aber nur für PHP-Quelltext. In anderen Code könnte es anders gehandhabt werden.

Umfassend

Zurück zu guten Beispielen. Sinnvoll ist ein informativer Vermerk im Header einer Datei. Hier ein umfassendes Beispiel in einer CSS-Datei:

/*
Theme Name: Codium Extend
Description: Codium Extend is a very simple wordpress theme with all the new features in WordPress 3.4: personalized menus, choosing a color for the background, ready for translation, custom header image ... This theme is ideal for anyone seeking simplicity with the full articles on the homepage! Bonus : this theme is optimized for handheld and mobile devices (iphone, ipad, and smartphone) with a responsive design. Un thème disponible en français aussi! 
Author: Henri Labarre
Theme URI: http://codiumextend.code-2-reduction.fr/
Author URI: http://www.vingthuitzerotrois.fr/
Version: 1.1.6
Tags: custom-colors, two-columns, fixed-width, custom-background, custom-header, threaded-comments, sticky-post, light, white, custom-background, translation-ready,custom-menu
License: GNU General Public License v2.0
License URI: http://www.gnu.org/licenses/gpl-2.0.html
*/

Manche Bereiche sollten wegen der Folgen nie unkommentiert beiben, hier aus einer .htaccess-Datei (beachte, hier wird mit Rautenzeichen auskommentiert: #):

# Prevent anybody from accessing the configuration file
<Files .htaccess>
order allow,deny
deny from all
</Files>

Optik

Auch die optische Unterteilung des Quelltextes durch Kommentare in funktionelle Bereiche ist wirkungsvoll. CSS-Files etwa können 500 bis zu 3.000 Zeilen umfassen. Da sollte fleissig sortiert und kommentiert werden. Je mehr, desto besser. Am Ende kommt meistens ein Kompressionstool ans Werk und schmeißt alle Kommentare heraus, aber bis dahin erfüllen sie ihre Funktion ganz sicher:

* =============================================================================
   HTML5 display definitions
   ========================================================================== */

article, aside, details, figcaption, figure, footer, header, hgroup, nav, section { display: block; }
/* =============================================================================
   Links
   ========================================================================== */

a { color: #00e; }
a:visited { color: #551a8b; }
a:hover { color: #06e; }
a:focus { outline: thin dotted; }

Marker

Manchesmal werden Kommentare selbst zur Markierung funktioneller Bereiche verwendet, zum Beispiel in Typo3 Content Management System. Hier findet sich im Template etwa folgendes zur Markierung von Inhaltsvereichen:

<!-- ###DOCUMENT_BODY### START--> 
<!-- ###DOCUMENT_BODY### END--> 

Man kann aufgrund dessen durchaus einer Website ansehen, welches Content Management im Hintergrund sitzt, wenn man sich auch mal die Kommentare im Quelltext anschaut.

One comment

  • Small Boss
    10. April 2014 - 11:35 | Permalink

    Moin Cornelius,

    diese Problematik ist mir nur allzu bekannt. Wenn ich mit andren Informatikern an einem Projekt arbeite und die mir dann ihren Code schicken ist es immer mühselig, herauszufinden, was die anderen überhaupt mit ihrem Code machen wollen. Solchen Leuten habe ich gleich mal deinen Artikel weitergeleitet.
    Ich danke dir dafür!

  • Comments are closed.

    QR Code Business Card