Marktplatz Downloads Tutorials Forum

Designnation bietet auch:

Tutorial hinzufügen

Beliebte Links Weitere Optionen

Tutorial suchen

Titel

Schlüsselwörter

PHP / MySQL Tutorial: PHP Scripte Dokumentieren -Teil 1- Sauberkeit und Namensgebung



Ranking: +5   Kommentare: 2   |   Bewertung: Keine Berechtigung!  


Vorwort



Ich möchte euch in einem 3 Teiligen Tutorial zeigen wie ihr eure PHP Scripte sauber und übersichtlich haltet und eine angemessene Dokumentation dazu erstellt. Eine Dokumentation ist oftmals nicht vorhanden und das zum Ärger der User die ein Script benutzen möchten und daran ein bisschen etwas anpassen möchten oder einen Fehler suchen.

Das wird in den Tutorials dran kommen:

-Teil 1- Sauberkeit und Namensgebung
-Teil 2- Kommentare richtig genutzt
-Teil 3- Dokumentation mit Hilfe von phpDocumentor



Teil 1 - Sauberkeit und Namensgebung



Wie Mama schon sagte: Sauberkeit ist das A und O. Nur es ist nicht Sinn und Zweck der Sache seine Variablen so kurz wie möglich zu benennen, oder gar nur Buchstaben zu verwenden. Beliebt hier sind $foo und $bar oder dann $a und $b. So... jetzt haben wir Buchstaben gespart, das Script kürzer gemacht und das ist auch Sauber!

Wer jetzt denkt das ist gut und hilft der irrt! Spätestens dann wenn ihr das Script größer werden lasst, immer mehr Dateien erstellt und andere in neue Includiert wisst ihr Irgendwann nicht mehr was jetzt die Variable $foo überhaupt beinhaltet. Wer seine Variablen so benennt, dem sei gesagt: Das ist foobar! Falls ihr irgendwann euer Script auch zum Download bereitstellt sind die User die es sich geladen haben und es anpassen möchten für ihre eigenen Zwecke einfach nur Hilflos und müssen sich auf Kosten einiger Stunden in das Script reinarbeiten, da hätten sie es auch selber schreiben können. Aber was kann man nun dagegen tun?

Variablen, Funktionen und Klassen



Als erstes wäre es nicht schlecht Variablen, Funktionen und Klassen passend zu benennen und am besten auch so das man diese sofort als Variable, Funktion oder Klasse erkennt. Hierbei könnt ihr total kreativ sein, jeder wie er am besten damit zurecht kommt. Ich habe mir folgendes angewöhnt:

Variablen

Variablennamen fangen bei mir immer klein an, vor dem eigentlichen Namen kommt der Typ meiner Variable damit ich immer sofort sehe was diese für einen Wert beinhaltet. Dafür habe ich folgende Abkürzungen benutzt:
  • $str - Zeichenkette (string)

  • $int - Ganzzahlen

  • $float - Gleitkommazahlen

  • $arr - Array

  • $bool - Boolsches 'true' oder 'false'



Erst nach der Abkürzung kommt der eigentlich Name für die Variable. Hier achte ich immer auf eine knappe, passende Aussage für meine Variable damit ich später im Script sofort sehe für was ich diese genutzt habe. Wie zum Beispiel:

$boolLoggedin: Hier sehe ich nun das meine Variable entweder true oder false enthällt und ich anhand ihr sehe ob man eingeloggt ist oder nicht.

Wie ihr seht habe ich die Variable klein Angefangen mit 'bool' und den eigentlichen Namen für die Variable wieder groß begonnen 'Loggedin'. Warum ich meine Variablen klein anfange, dazu kommen wir gleich.

Funktionen

Funktionen beginne ich immer mit einem Wort das grob aussagt was die Funktion macht. Danach der eig. Name der Funktion bei dem jedes Wort mit einem Großbuchstaben beginnt.

Um Funktionsnamen zu finden frage ich mich immer 'Was macht die Funktion?'. Auch hier habe ich wieder das ein oder andere was ich vor den eigentlichen Namen der Funktion stelle:
  • function read()

  • function erase()

  • function sort()

  • function check()

  • function log()

  • usw...



um dann zu Wissen was genau die Funktion macht, zumindest im groben, ohne diese noch einmal durchschauen zu müssen benenne ich passend zu meiner Funktion der Funktion den Namen der Funktion

Also einfach gesagt bzw gezeigt:
  • function readDataFromDB()

  • function eraseDataFromDB()

  • function sortDataByDate()

  • function checkIP()

  • function logError()

  • usw...



Klassen

Klassennamen beginne ich immer mit einem Großbuchstaben, dann sehe ich sofort das es sich hier um eine Klasse handelt. Auch hier sollte man passende Namen suchen, am besten sucht man sich ein Hauptwort womit man die Klasse passend trifft. Hier kann ich euch nur auf den Weg geben: Erster Buchstabe groß->Klasse! =)




Schlusswort

Jetzt solltet ihr eure Variablen, Funktionen und Klassen ein bisschen passender benennen können und später im Script sehen was sache ist. Das erspart viel Arbeit und Nerven! Nicht nur die eigenen und dafür werden euch später leute dankbar sein.

Morgen kommt dann der 2. Teil bei dem es um die Kommentare selber geht. Aber einen Vorteil hat die Namensgebung aufjedenfall schon jetzt, man braucht später weniger Kommentare um zu wissen was sache ist! :)

Lieben gruß der floH

PS: Das ist mein erstes Tutorial also entschuldigt falls es euch nicht taugt, oder Schreibfehler vorhanden sind ;)

Veröffentlicht von: floH_
Veröffentlicht am: 15 May. 2008
Bookmarks: social bookmarking yigg it Linkarena Technorati Yahoo Mr. Wrong
Schlüsserwörter: Doku Dokumentation Kommentare PHP Sauberkeit


Themenverwandte Tutorials


Kommentar(e) (2)


QXARE sagt:

oder das anschauen und wissen wies richtig geht: http://php-coding-standard.de/php_coding_standard.php

nix gegen dich, aber wieso das Rad neu erfinden...

Zuletzt bearbeitet am: 26 May. 2008 12:48:23

26 May. 2008 12:48:07 • Antworten


deleted_1300463630 sagt:

Jetzt haben Anfänger, *hust* wie ich *hust* wenigstens schonmal eine Ahnung wie sie anfangen können ;) nice tutorial

18 May. 2008 19:08:17 • Antworten



Anfang

<<

1

>>

Ende

Kommentar eintragen


!! Jetzt kostenlos anmelden oder einloggen und mitdiskutieren!


Partner: • Designer in ActionFlash HilfeTutorials.dePixelio.deFlashstar BlogLizenzfreie Bilder