Keine Abkürzungen in PHP? (PHP Coding Standard)

[Solaris]

Aufgrund einer Diskussion mit einem Kollegen habe ich mir mal Coding Standards angeschaut. Hauptsächlich diese:

PHP Coding Standard (Rewritten for PHP by Fredrik Kristiansen / DB Medialab, Oslo 2000-2003)
und
PHP Coding Standard auf deutsch (von Claus van Beek)

/**
 * Oeffnet die Verbindung zum RDBMS und selektiert die DB.
 * @param $h: Host
 * @param $b: Benutzer
 * @param $p: Passwort
 * @param $db: Datenbank
 * @return $v: Verbindung zum RDBMS
**/
function dbo($h, $b, $p, $db)
{
  $v = mysql_connect($h, $b, $p);
  mysql_select_db($db, $v);
  return $v;
} 

Wie ich festgestellt habe machen andere hier im Forum das auch so, aber beide Coding Standards erlauben Abkürzungen nur im begrenzten Maße...Ich frage mich warum?

Das ist doch viel übersichtlicher und jede Variable ist auch erklärt...

Beachtet Ihr einen (PHP) Coding Standard?

CU Solaris

[Gaert]

Hallo,

nur weil du variablen dokumentierst wird das coding noch nicht übersichtlich... für mich persönlich ist dein Beispiel ziemlich schlechtes coding.
Lass nur die funktion mal etwas länger und komplexer werden. Nach der konvention "Variable = max. 2 Buchstaben, bevorzugt Anfangsbuchstabe der Bedeutung" wirst du schnell an deine Grenzen stossen, bzw. aus dem Dokumentieren nicht mehr herauskommen.
Ich vertrete die Meinung dass das Coding so selbsterklärend sein sollte, dass (überflüssige, den Code aufblähende) Kommentare nicht nötig sind.
Ich finde Variablennamen werden in PHP generell etwas lax verwendet - in anderen Sprachen gibt es hier viel strengere Konventionen, bei denen neben der Bedeutung des Inhalts auch der Datentyp (den es in PHP ja eigentlich nicht wirklich gibt) und der Kontext in dem Variablennamen codiert sind.

So wäre es beispielweise möglich statt "$h" "$p_host" zu verwenden --> damit wäre klar definiert, dass es sich um einen Host mit Typ String handelt, der als Funktionsparameter übergeben wurde. "$v" wäre als "$l_dbconnection" als funktionslokale Variable gekennzeichnet welche ein Handler einer Datenbankverbindung enthält. Ähnlich könnte man mit globalen ($g_globalevariable) Variablen verfahren. Spezialfälle wie Objekte oder Arrays könnte man ebenfalls so markieren z.b. $la_lokalesarray, $po_uebergebenesobjekt, usw.

Gruß,

Gaert

[Pingu]

Solche Coding Standards kommen ja auch nicht von ungefähr. Sicherlich, wer bisher still in seinem Kämmerlein nur seine eigenen Projekte verfolgt hat, hat es schwer den Sinn zu verstehen. Wer aber mal in verschiedenen Firmen mit verschiedenen Projekten und den unterschiedlichsten Leuten und damit Charakteren zu tun hatte, weiß solche Standards zu schätzen.
Dies betrifft gerade auch die Benennung. Laß Deine Funktion mal über zwei oder drei Bildschirmseiten gehen und habe mehrere solche Funktionen. Wenn man jetzt beim Debuggen ständig zwischen den Funktionen hin und herspringt, weiß man am Ende nicht mehr wirklich wo welche Bedeutung eine solche Variable nun hat oder auch nicht. Wenn man bei Debuggen auf eine Remote Console angewiesen ist, hat man auch keine Möglichkeit sich die Fenster schön anzuordnen, weil da gibt es nur ein Fenster.

Pingu

[undefined]

Also dein Beispiel ist in meinen Augen voll und ganz OK. Ich mache es selbst genauso. Es ist in der Dokumentation nicht entscheidend wie du innerhalb der Funktion oder Methode deine Variablen Deklarierst (schließlich must du den Überblick behalten und nicht Aussenstehende). Es ist nur entscheidend wie gut du Dokumentierst.
Wozu sollte man auch unnütz Lange Variablen Namen verwenden wenn nur die Ausgabe wichtig ist

   /**
   * @short Image Groesse Skallieren
   * @param [String]  $a Bildpfad
   * @privatesection
   * @return Array( ImageSRC, Width, Height, Neue Breite, Neue Hoehe );
   */
   private function iu_ImageScale( $a )
   {
      if ( ! is_string( $a ) || ! is_readable( $a ) )
         return false;

      $i = getimagesize( $a );
      $w = (int)$i[0];
      $h = (int)$i[1];
      if ( $w > $this->MAX_W ) {
         $r = ( $this->MAX_W / $w );
         $nw = (int)round( $w * $r );
         $nh = (int)round( $h * $r );
         if ( $nh > $this->MAX_H ) {
            $r = ( $this->MAX_H / $nh );
            $nw = (int)round( $nw * $r );
            $nh = (int)round( $nh * $r );
         }
      } else if ( $h > $this->MAX_H ) {
         $r = ( $this->MAX_H / $h );
         $nw = (int)round( $w * $r );
         $nh = (int)round( $h * $r );
         if ( $nw > $this->MAX_W ) {
            $r = ( $this->MAX_W / $nw );
            $nw = (int)round( $nw * $r );
            $nh = (int)round( $nh * $r );
         }
      } else {
         $nw = 0;
         $nh = 0;
      }
      return array( $a, $w, $h, $nw, $nh );
   } 

Reicht für mich völlig aus.

[ClausVB]

Solche Coding Standards kommen ja auch nicht von ungefähr. Sicherlich, wer bisher still in seinem Kämmerlein nur seine eigenen Projekte verfolgt hat, hat es schwer den Sinn zu verstehen. Wer aber mal in verschiedenen Firmen mit verschiedenen Projekten und den unterschiedlichsten Leuten und damit Charakteren zu tun hatte, weiß solche Standards zu schätzen.

Dem gebe ich zu 100% recht. Alleine kann man so programmieren, aber im Team mit 3 oder mehr Mitarbeitern wird sich unter Garantie nur einer (wenn überhaupt) mit allen Abkürzungen auskennen.

Es stimmt, was undefined gesagt hat, dass Deine Funktion die Schnittstellen nur nach außen gut beschreiben muss, aber das gilt nur so lange, bis ein Bug auftaucht und Du in Urlaub bist. Dann müssen die anderen nämlich Deinen Source-Code debuggen und den Fehler suchen.

Das es dabei jede Menge Flüche gibt, kann ich Dir garantieren.

Ich habe auch den angesprochenen Post bzw. das Problem von undefined gelesen. Ich war nur am hin und herscrollen, weil ich die Abkürzungen immer wieder nachlesen musste. Vielleicht ist auch mein Gedächtnis zu schlecht ...

Ich neige dazu eher zu lange Namen zu wählen. Auch das kann unübersichtlich werden, aber ein Azubi, der mit mir zusammenarbeiten darf/muss, hat mich mal für meine Code-Strukturen gelobt.

Hier ein Beispiel:

// Ich werde hier ausnahmsweise englische Variablennamen verwenden, weil GET und PUT FTP-Befehle sind
$get = new LoginGetPutProtokollierung('129.101.163.79', 'kennung', 'passwort');
$get->VerzeichnisWechsel('./');
$get->TempPfadAnlegen('tmp/');
$dateien = $get->DateienHolen();
$get->ProtokollAusgebenUndInMysqlEinfuegen('Quellserver');
$get->VerbindungSchliessen(); 

Beispiel für eine Methode:

/**
 * Wechselt auf dem FTP-Server mit ftp_chdir() das Verzeichnis.
 * @param   $ftp_pfad: Enhält einen Pfad bzw. ein Unterverzeichnis wie "daten/zip/"
 * @return  noch kein Return-Parameter (:TODO: TRUE oder FALSE wäre gut)
**/
function VerzeichnisWechsel($ftp_pfad)
{
    // Eigenschaften initialisieren
    $this->ftpPfad = $ftp_pfad;

    // ftp_chdir() ausführen und abspeichern
    $this->verzeichnisWechseln = ftp_chdir($this->verbindung, $this->ftpPfad);
} 

Wie man sehen kann, haben wir uns im Team auf unterschiedliche Namenskonventionen für Variablen geeinigt:
- Variablen in einer Klasse (Eigenschaften bzw. Attribute) => $this->ftpPfad
- Variablen in einer Funktion oder einem "normalen" Skript: $ftp_pfad

Auf Abkürzungen wie "m" für "Member attribute" oder "Membervariable" verzichten wir. Ebenso ist "g_count" bei uns nicht erwünscht (g = global).

Das wir solche Verbrechen nicht begehen

$berechnetes_ergebnis = $wurzel * 5;
$berechnetes_ergebnis = 'Jetzt ist es ein String'; 

versteht sich von selbst in unserem Team.

Meine 2 Cent.

Gruß
Claus

PS: Weitere PHP Coding Standards ...
http://www.phpbb.com/phpBB/docs/codingstandards.htm
http://www.mantisbt.org/guidelines.php
http://pear.php.net/manual/en/standards.php
(PEAR Coding Standards sind IMHO nicht ganz ausgereift)

[Turbohummel]

$i in Schleifen - ok. $db für das Datenbankobjekt - ok. $r für Ergebnis - ok, $b für Puffer - ok.

Aber alles andere würde ich sprechend schreiben.
Ich empfehle die Schreibweise mit dem Datentyp (übrigens auch in Java):
$s_dasisteinstring.

Die Mehrschreibarbeit macht sich lohnend, wenn du ein Stück Code von dir in nem halben Jahr wieder anguckst.

[ClausVB]

Die Mehrschreibarbeit macht sich lohnend, wenn du ein Stück Code von dir in nem halben Jahr wieder anguckst.

Dem gebe ich absolut recht. Nicht nur in einem Team helfen solche Konventionen, auch alter eigener Code wird durch Kommentare und lange, sinnvolle Variablennamen besser lesbar, auch dann, wenn man ihn selbst geschrieben hat.

Nicht zustimmen tue ich der Philosophie, dass "$r = $result" ist, das gleiche gilt für die Abkürzung "$rst". Beides könnte auch "$reset" bedeuten. Aus dem Zusammenhang "$r = mysql_query(...)" wird dann wieder klar, dass es "result" (Ergebnis) bedeutet, aber ein Variable ist für mich dann gut benannt, wenn nur der Bezeichner klare Auskunft über die Variable gibt.
Ein "$dezimale_zahl" wird von einem (guten) Programmierer nie mit einem String belegt und gibt mit ECHO sehr wahrscheinliche einen Wert wie "2.87" aus.

Neben meiner Meinung (Regel 8: Alle Bezeichner werden aussagekräftig und eindeutig definiert) will ich hier auch noch kurz zwei Zitate anbringen.

In der Regel sollten Sie Variablennamen so wählen, dass sie etwas über den Zweck der Variablen aussagen. $r ist wahrscheinlich nicht so aussagekräftig wie $zeilen_laenge. (...) Ebenso können richtig platzierte Unterstriche das Lesen und Verstehen eines Variablennamens erleichtern, besonders dann, wenn der Programmierer, der Ihre Programme pflegen soll, einen anderen sprachlichen Hintergrund hat als Sie.

und

Wie schon bei den Variablen wird auch für Prozeduren und Funktionen ein möglichst vollständiger, beschreibender Name mit mehreren Wörtern benutzt. (...)

Bei beiden Büchern handelt es sich meiner Meinung nach um Standard-Werke. Ich würde mir über Abkürzungen immer Gedanken machen und ein
"$connect_rdbms"
nur dann verwenden, wenn ich die Abkürzung RDBMS wirklich als bekannt voraussetzen kann.

Gruß
Claus

[Meillo]

... wie hat da mal Jemand so schön gesagt: "Treffende Bezeichner sind wichtiger als Kommentar!"

und ein Anderer meinte, dass bei ihm $i, $ii in Zählschleifen, $f für einen Dateizeiger (falls es nur einen einizigen gibt) und $h als String-Helper, die einzigen erlaubten kurzen Variablennamen seien.