[Erledigt] Lesbar kommentieren

Haze · 18.11.2009, 17:26

Hi,

ich fange gerade an etwas längere Skripte zu schreiben und stelle mir die Frage, wie man Diese wohl am besten kommentiert.

Jede Zeile möchte ich nicht kommentieren, aufgrund des Aufwands. In meinen Klassen habe ich immer eine Zeile über der Funktion einen Kommentar eingefügt, der beschreibt, was die Funktion macht.

Ich aber so kommentieren, dass andere, die den Code vielleicht später mal lesen und nutzen ihn auch verstehen können.

Gibt es vielleicht ungeschriebene Gesetze oder habt ihr einige Tips?

Danke für Eure Hilfe,
Haze

$gast · 18.11.2009, 17:38

Hi,

PHP Coding Standard
Da findest du ein paar Tipps zur Kommentierung...

nikosch · 18.11.2009, 17:49

- Kommentiere keine Trivia:

PHP-Code:

  $counter++; // erhöht den Zähler um 1

Manche Dinge sind selbsterklärend. Eine sprechende Variable ist hier sinnvoller als ein Kommentar. Beschreibe oben lieber an geeigneter Stelle, was der Zähler zählt.

- Kommentiere die Bedeutung, nicht die Funktion
schlecht:

Zitat:

// ruft den Parser auf
$out = myParser ($in);

besser:

Zitat:

// parst $in - schreibt seine XML-Strukturelemente in $out
$out = myParser ($in);

- Kommentiere unbedingt Abweichungen von typischen Mustern, Abläufen
Alles was man nicht auf einen Blick versteht - ohne mit dem Projekt vertraut zu sein - muß beschrieben werden.

Phoscur · 18.11.2009, 19:30

Guter Code kommt fast ohne Kommentare aus. Du musst die Variablen und Funktionen (besser Methoden OOP) nur ordentlich benennen. Der Code sollte sich lesen lassen wie ein Buch. Das heißt du musst da Kommentieren, wo es besonders schwierig zu verstehen ist. Meist sollte man den Teil auch isoliert in einer Methode unterbringen und diese mit einem geeigneten Namen benennen, der dann auch schon meist als Beschreibung ausreicht. Vermeide allgemein verworrenen Code zu schreiben, den will keiner lesen!

Haze · 18.11.2009, 19:37

Hi,

danke für die guten Antworten. Die Webseite kenne ich noch nicht, aber ich werde Sie mir auf jeden Fall zu Gemüte führen.

Grüße,
Haze

nikosch · 18.11.2009, 19:41

Zitat:

Meist sollte man den Teil auch isoliert in einer Methode unterbringen und diese mit einem geeigneten Namen benennen

Zu diesem Hinweis gibt es auch eine verwandte Diskussion um Refaktorierung - Jeder strukturell zusammengehörige Codeblock, der eine gewisse Zahl von Zeilen überschreitet (Angaben differieren, i. A. 20 - 40, keinesfalls mehr als eine Bildschirmseite), sollte aufgebrochen und in Teilstrukturen, z.B. (Helper-)Methoden (OOP) oder Funktionen (prozedurale Programmierung) abgebildet werden.

Phoscur · 18.11.2009, 22:30

Dort habe ich das wahrscheinlich her, bei mir liegt gerade ein Refactoringbuch herum, könnte aber auch aus Implementation Patterns sein.

Haze · 19.11.2009, 08:29

Hi,

danke auch nochmal für die Tips. Ich werde meinen Code wohl nochmal überarbeiten müssen.

Grüße,
Haze

Themen-Optionen
Druckbare Version zeigen Jemanden per E-Mail auf dieses Thema hinweisen
Thema bewerten
Thema bewerten:

Ähnliche Themen
Thema	Autor	Forum	Antworten	Letzter Beitrag
PHP Manual nicht lesbar?	Alex04	PHP Tipps 2009	5	01.09.2009 09:17
Verknüpfung zweier Tabellen zur Ausgabe klappt nicht	Lesnivila	PHP Tipps 2009	40	13.03.2009 13:20
Wie weit kommentieren?	Waq	Off-Topic Diskussionen	20	29.07.2005 23:52
Upload erst nach chmod lesbar	pherfinion	PHP Tipps 2005	2	11.03.2005 10:26
Bilder kommentieren / bewerten		PHP Tipps 2004-2	11	21.11.2004 11:09
Bilder bewerten / kommentieren - Skript gesucht		Beitragsarchiv	6	19.11.2004 13:59
Suche Script: Kommentieren von Textabschnitten		Beitragsarchiv	1	08.11.2004 21:38
Internet-Explorer: nach Download-Script HTML nimmer lesbar		PHP Tipps 2004	1	23.10.2004 14:00

18.11.2009, 17:26
Haze Neuer Benutzer Registriert seit: 23.10.2009 Beiträge: 18 PHP-Kenntnisse: Anfänger	[Erledigt] Lesbar kommentieren Hi, ich fange gerade an etwas längere Skripte zu schreiben und stelle mir die Frage, wie man Diese wohl am besten kommentiert. Jede Zeile möchte ich nicht kommentieren, aufgrund des Aufwands. In meinen Klassen habe ich immer eine Zeile über der Funktion einen Kommentar eingefügt, der beschreibt, was die Funktion macht. Ich aber so kommentieren, dass andere, die den Code vielleicht später mal lesen und nutzen ihn auch verstehen können. Gibt es vielleicht ungeschriebene Gesetze oder habt ihr einige Tips? Danke für Eure Hilfe, Haze


Mister Ad PHP Code Flüsterer Registriert seit: 21.08.2005 Beiträge: 4682 PHP-Kenntnisse: Fortgeschritten

18.11.2009, 17:38
$gast Benutzer Registriert seit: 05.08.2009 Beiträge: 93 PHP-Kenntnisse: Anfänger	Hi, PHP Coding Standard Da findest du ein paar Tipps zur Kommentierung... __________________ PHP-Code: `echo "Hello World";`

18.11.2009, 19:30
Phoscur Erfahrener Benutzer Registriert seit: 01.12.2008 Beiträge: 450 PHP-Kenntnisse: Fortgeschritten	Guter Code kommt fast ohne Kommentare aus. Du musst die Variablen und Funktionen (besser Methoden OOP) nur ordentlich benennen. Der Code sollte sich lesen lassen wie ein Buch. Das heißt du musst da Kommentieren, wo es besonders schwierig zu verstehen ist. Meist sollte man den Teil auch isoliert in einer Methode unterbringen und diese mit einem geeigneten Namen benennen, der dann auch schon meist als Beschreibung ausreicht. Vermeide allgemein verworrenen Code zu schreiben, den will keiner lesen! __________________

18.11.2009, 19:37
Haze Neuer Benutzer Registriert seit: 23.10.2009 Beiträge: 18 PHP-Kenntnisse: Anfänger	Hi, danke für die guten Antworten. Die Webseite kenne ich noch nicht, aber ich werde Sie mir auf jeden Fall zu Gemüte führen. Grüße, Haze

18.11.2009, 22:30
Phoscur Erfahrener Benutzer Registriert seit: 01.12.2008 Beiträge: 450 PHP-Kenntnisse: Fortgeschritten	Dort habe ich das wahrscheinlich her, bei mir liegt gerade ein Refactoringbuch herum, könnte aber auch aus Implementation Patterns sein. __________________

19.11.2009, 08:29
Haze Neuer Benutzer Registriert seit: 23.10.2009 Beiträge: 18 PHP-Kenntnisse: Anfänger	Hi, danke auch nochmal für die Tips. Ich werde meinen Code wohl nochmal überarbeiten müssen. Grüße, Haze