Witaj, Gościu O nas | Kontakt | Mapa
Wortal Forum PHPEdia.pl Planeta Kubek IRC Przetestuj się!
Spis treści

Spis treści

O autorze

O autorze

Grzegorz (scanner) Tlołka
Reklama

Reklama

Podobne Artykuły

Poniżej znajduje się lista podobnych artykułów:
Brak powiązanych artykułów

Standardy kodowania

Poniższa specyfikacja ujednolica standardy kodowania przyjęte i stosowane przez programistów pracujących w grupie PHP.PL DevTeam. Ma ona zastosowanie do wszystkich projektów autorstwa DevTeam. Podstawą tego dokumentu są:

Podstawowym wymogiem stawianym programistom chcącym dołączyć do PHP.PL DevTeam 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 php.pl (np. forumowicze).

1. Wcięcia

Jako wcięć powinno się używać 4 (czterech) spacji. Niedozwolone jest używanie znaku tabulacji. Znaczniki kodu PHP znajdują się w kolumnie zerowej, wszystko znajduje się miedzy nimi, jest 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
?>

2. Struktury kontrolne

Zaliczamy do nich konstrukcje 'if', 'for', 'while', 'switch' itp. Poniżej znajduje się przykład struktury 'if', którą będziesz najczęściej używał:

<?php 
    if ( ( expr_1 ) || ( expr_2 ) ) 
    { 
        // akcja_1; 
    } 
    elseif ( !( expr_3 ) && ( expr_4 ) ) 
    { 
        // akcja_2; 
    } 
    else 
    { 
        // domyślna_akcja; 
    } 
?>

W strukturach kontrolnych powinna występować 1. (jedna) spacja przed i po nawiasie.

Zawsze używaj nawiasów klamrowych. Nawet wtedy, gdy nie są one potrzebne. Zwiększają one czytelność kodu i zmniejszają liczbę logicznych błędów. 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 wyrazenie 
    if ( expr ) statement;

    // zle - brak klamer 
    if ( expr ) 
        statement;

    // Dobrze 
    if ( expr ) 
    { 
        statement; 
    } 
?>

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( $bar, $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 przypadku jaki przedstawiono poniżej:

<?php 
    $varShort = foo( $bar1 ); 
    $variableLong = foo( $bar1 ); 
?>

4. Definicje funkcji

Przykładowa definicja funkcji:

<?php 
    function someFunction( $arg1, $arg2 = '' ) 
    { 
        if ( expr ) 
        { 
            statement; 
        } 
        return $var; 
    } 
?>

Argumenty, które mają domyślną wartość umieszczamy na końcu listy argumentów funkcji. Zawsze staraj się aby Twoja 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 prostu sposób opisywać komentowany blok skryptu. Dodatkowo każdy z plików musi zawierać nagłówek według szablonu:

<?php
/**
 *
 */
?>

Komentarze zawierają następujące znaczniki phpDocumentator:

  • @access
  • @author
  • @copyright
  • @deprecated
  • @example
  • @ignore
  • @internal
  • @link
  • @see
  • @since
  • @tutorial
  • @version
  • inline {@internal}}
  • inline {@inheritdoc}}
  • inline {@link}}

Tagi phpDocumentor są bardzo podobne do do tagów JavaDoc dla języka programowania Java. Znaczniki są przetwarzane tylko wtedy, gdy są jako pierwsze w nowej linii DocBlock. Możesz używać znaku "@" w dowolnie w całym dokumencie tak długo, dopóki nie zaczyna on nowej linii. Na przykład:

<?php
    /**
     * przykład znaczników
     * @author ten znacznik jest parsowany, ale znacznik @version jest ignorowany
     * @version 1.0 ten znacznik wersji jest przetwarzany
     */
?>

Znaki, których phpDocumentor nie rozpoznaje nie będą przetwarzane i będą wyświetlane w tekście jakby były częścią dłuższego opisu DocBlocku. Przykład poniżej wyświetli tekst "przykład znaczników @foobar to jest głupie" a także pokaże autora jako "ten znacznik jest przetwarzany, ale znacznik @version jest ignorowany".

<?php
    /**
     * przykład znaczników
     * @foobar to jest głupie
     * @author ten znacznik jest przetwarzany, ale znacznik @version jest ignorowany
     */
?>

Znaczniki szeregowe wyświetlane są w tekście tak jak się pojawiają i nie są oddzielane od opisu. W wersji 1.2 jest kilka znaczników szeregowych. Lista dopuszczalnych znaczników szeregowych jest rózna dla tutoriali i zwykłych dokumentacji kodowych.

Przykład poniżej wyświetli tekst "ta funkcja ciężko pracuje z foo() żeby rządzić światem" gdzie foo() jest hiperłączem prowadzącym do dokumentacji funkcji foo().

<?php
    /**
     * przykład znaczników szeregowych
     *
     * ta funkcja ciężko pracuje z {@link foo()} żeby rządzić światem
     */
    function bar()
    {
    }

    function foo()
    {
    }
?>

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. Tagi kodu

Zawsze używamy znaczników

<?php
?>

do oznaczenia kodu PHP, nigdy nie stosując wersji krótkiej

<?
?>

8. 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

9. 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 muszą mieć na początku nazwy określony rodzaj. Wszystkie nazwy (funkcje, klasy, zmienne pliki itp.) zapisujemy w języku angielskim.

<?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 plikow 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
Informacje na podobny temat:
Wasze opinie
Wszystkie opinie użytkowników: (0)
Mentax.pl    NQ.pl- serwery z dodatkiem świętego spokoju...   
O nas | Kontakt | Mapa serwisu
Copyright (c) 2003-2017 php.pl    Wszystkie prawa zastrzeżone    Powered by eZ publish Content Management System eZ publish Content Management System