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
// wcięcie podstawowe
// wcięcie poziom 1
// wcięcie poziom 2
// wcięcie poziom 1
// wcięcie podstawowe
?>
<?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.if( (warunek_1) || (warunek_2) )
{
// akcja_1;
}
elseif( !(warunek_3) && (warunek_4) )
{
// akcja_2;
}
else
{
// domyślna_akcja;
}
?>
<?php
if( warunek )
...
?>
Jedna spacja również powinna występować przed i po operatorach:if( warunek )
...
?>
arytmetycznych (+, -, *, /, %),
$a + $b;
$a - $b;
$a * $b;
$a / $b;
$a % $b;
przypisania (łączone operatory przypisania) (=, +=, -=, *=, /=, %=, .=),
$a - $b;
$a * $b;
$a / $b;
$a % $b;
$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
$a != $b
$a <> $b
$a < $b
$a > $b
$a <= $b
$a >= $b
logicznych (&&, ||, and, or, xor)
$a === $b
$a != $b
$a <> $b
$a < $b
$a > $b
$a <= $b
$a >= $b
$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:$a || $b
$a and $b
$a or $b
$a xor $b
<?php
// zle - brak klamer, źle umiejscowione wyrażenie
if( warunek ) akcja;
// zle - brak klamer
if( warunek )
akcja;
// Dobrze
if( warunek )
{
akcja;
}
?>
// 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 );
?>
$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 );
?>
$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:
function someFunction( $arg1, $arg2 = '' )
{
if( warunek )
{
akcja;
}
return $var;
}
?>
<?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;
}
?>
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:
// Przyklad klasy i metody
$Smarty->fetch( $strTemplateName );
// Przyklad funkcji
function Foo( $strBar )
// Przyklad zmiennej
$objSomeObject
?>
$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:
$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()
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
name.test.php //plik z klasą testową tegoż modułu
name.inc.php //plik includowany do klasy modulu
wersja 1.0 2005.07.15.