Galka.MountLab.net
Poligon doświadczalny Damiana Gałki.

Programowanie

Standardy kodowania

Poniższa specyfikacja ujednolica standardy kodowania przyjęte i stosowane przez członków MountLab Group. Ma ona zastosowanie do wszystkich projektów autorstwa Mountlab Group.

Podstawowym wymogiem stawianym programistom w MountLab Group jest zaakceptowanie i stosowanie się do poniższej specyfikacji. To samo dotyczy wszystkich kodów, które chciałbyś dołączyć do naszych projektów. Zaleca się także, aby do poniższych standardów dostosowały się również osoby luźniej związane z naszą grupą (np. forumowicze).

1. Wcięcia

Jako wcięć używamy 2 (dwóch spacji) przy jednoczesnym zakazie używania znaku tabulacji. Bez względu na to w jakim edytorze powstaje kod. Znaczniki rozpoczynające i kończące kod PHP znajdują się w kolumnie zerowej, a wszystkie pozostałe bloki pomiędzy nimi odpowiednio wcięte. Dozwolone jest pominięcie podstawowego poziomu wcięć.
<?php
 // wcięcie podstawowe
   // wcięcie poziom 1
     // wcięcie poziom 2
   // wcięcie poziom 1
 // wcięcie podstawowe
?>
Zawsze używamy tagów rozpoczynających kod w postaci
<?php
   ...
?>
nigdy nie stosując wersji krótkiej
<?
   ...
?>

2. Struktury kontrolujące

Do struktur kontrolujących zaliczamy konstrukcje “if”, “for”, “while”, “switch”, itp. Przykład poniżej przedstawia instrukcję warunkową “if”:
<?php
 if( (warunek_1) || (warunek_2) )
 {
   // akcja_1;
 }
 elseif( !(warunek_3) && (warunek_4) )
 {
   // akcja_2;
 }
 else
 {
   // domyślna_akcja;
 }
?>
W strukturach kontrolujących powina występować 1 (jedna) spacja po nawiasie otwierającym i przed zamykającym, oddzielając tym samym podane wewnątrz nich warunki.
<?php
if( warunek )
   ...
?>
Jedna spacja również powinna występować przed i po operatorach:
arytmetycznych (+, -, *, /, %),
$a + $b;
$a - $b;
$a * $b;
$a / $b;
$a % $b;
przypisania (łączone operatory przypisania) (=, +=, -=, *=, /=, %=, .=),
$a = 0;
$a += $b;
$a -= $b;
$a *= $b;
$a /= $b;
$a %= $b;
$a .= $b;
porównań (==, ===, !=, <>, <, >, <=, >=),
$a == $b
$a === $b
$a != $b
$a <> $b
$a < $b
$a > $b
$a <= $b
$a >= $b
logicznych (&&, ||, and, or, xor)
$a && $b
$a || $b
$a and $b
$a or $b
$a xor $b
Obowiązkowo należy używać nawiasów klamrowych, nawet tam, gdzie nie są wymagane. Obydwa nawiasy klamrowe powinny znajdować się w nowych liniach, i powinny być odpowiednio wcięte. Wyrażenie zawarte w klamrach powinno zaczynać się w nowej linii:
<?php
 // zle - brak klamer, źle umiejscowione wyrażenie
 if( warunek ) akcja;

 // zle - brak klamer
 if( warunek )
   akcja;

 // Dobrze
 if( warunek )
 {
   akcja;
 }
?>

3. Wywołania funkcji

Funkcje powinny być wywoływane bez żadnej spacji pomiędzy nazwą funkcji a początkowym nawiasem, jedną spacją pomiędzy pierwszym nawiasem i pierwszym parametrem, jedną spacją pomiędzy przecinkiem a parametrem, oraz jedną spacją pomiędzy ostatnim parametrem a kończącym nawiasem.
<?php
 $var = foo( $bar1, $bar2, $bar3 );
?>

Jak widać na powyższym przykładzie, jedna spacja powinna znaleźć się po obu stronach znaku równania ('='). Aby zwiększyć czytelność kodu możesz zwiększyć ilość spacji, ale w taki sposób jak pokazano poniżej:
<?php
 $varShort     = foo( $bar1 );
 $variableLong = foo( $bar1 );
?>

4. Definicje funkcji

Przykładowa definicja funkcji:
<?php
 function someFunction( $arg1, $arg2 = '' )
 {
   if( warunek )
   {
     akcja;
   }
   return $var;
 }
?>
Argumenty, które mają domyślną wartość umieszczamy na końcu listy argumentów funkcji. Zawsze staramy się, aby funkcja zwracała jakąś wartość, przynajmniej TRUE lub FALSE określające powodzenie wykonania funkcji. Poniżej znajduje się bardziej rozbudowany przykład:
<?php
 function connection( &$dsn, $persistent = false )
 {
   if( is_array( $dns ) )
   {
     $dns_info = &$dns;
   }
   else
   {
     $dns_info = BD::parseDNS( $dns );
   }

   if( !($dns_info) || !($dns_info['phpType']) )
   {
     return $this->addError();
   }

 return TRUE;
 }
?>

5. Komentarze

Wszystkie komentarze piszemy w języku polskim, komentarze powinny w jasny i prosty sposób opisywać komentowany blok skryptu. Dodatkowo każdy z plików musi zawierać nagłówek według szablonu:
<?php
/**
 *
 */
?>

6. Dołączanie kodu

Do dołączania plików z klasami czy bibliotekami PHP, zawsze używaj tylko i wyłącznie funkcji require_once.

7. Przykładowe adresy

Dla wszystkich przykładowych adresów URL i mail używaj "example.com", "example.org" i "example.net", np:
Email: someone@example.com
WWW: http://www.example.com
FTP: ftp://ftp.example.net

8. Nazewnictwo

Wszystkie nazwy powinny być czytelne i opisujace w stopniu podstawowym swoje zastosowanie. Nazwa zmiennej zaczyna się od małej litery. Nazwy funkcji, klas i metod mogą zaczynać się od dużej litery. Słowa składowe pisane są nierozdzielnie i każde z nich zaczyna się z dużej litery. Nazwy zmiennych powinny mieć na początku nazwy określony rodzaj. Wszystkie nazwy (funkcje, klasy, zmienne pliki itp.) zapisujemy w języku angielskim (Dopuszczalny jest język polski, ale zabronione jest ich mieszanie).
<?php
 // Przyklad klasy i metody
 $Smarty->fetch( $strTemplateName );

 // Przyklad funkcji
  function Foo( $strBar )
   
 // Przyklad zmiennej
  $objSomeObject
?>
Wyszczególnienie wszystkich typów danych:
$mixVar    // Zmienna nieokreślonego (lub dowolnego) typu.
$intVar    // Zmienna typu integer
$fltVar    // Zmienna zawierająca liczbe zminnoprzecinkową (float)
$blnVar    // Typ logiczny (boolean)
$strVar    // Łańcuch znaków (string)
$arrVar    // Tablica (array)
$objSmarty // Objekt. Nazwa obiektu może nie zawierać przyrostka typu (patrz listing powyżej)
$resFile   // Identyfikator zasobów (resource) zwracany np. przez funkcje mysql_connect()
Nazwy plików piszemy małymi literami, zaznaczając typ pliku:
name.class.php  //plik z klasą modułu
name.test.php   //plik z klasą testową tegoż modułu
name.inc.php   //plik includowany do klasy modulu


Na górę strony

wersja 1.0 2005.07.15.