Wprowadzenie do Zend Framework

     Nauka Zend Framework

    appendix

     Przewodnik po Zend Framework


  • Zend_Gdata
  • Zend_Http
  • Zend_InfoCard
  • Zend_Json
  • Zend_Layout
  • Zend_Ldap
  • Zend_Loader
  • Zend_Locale
  • Zend_Log
  • Zend_Mail
  • Zend_Markup
  • Zend_Measure
  • Zend_Memory
  • Zend_Mime
  • Zend_Navigation
  • Zend_Oauth
  • Zend_OpenId
  • Zend_Paginator
  • Zend_Pdf
  • Zend_ProgressBar
  • Zend_Queue
  • Zend_Reflection
  • Zend_Registry
  • Zend_Rest

  • Zend_Search_Lucene
  • Zend_Serializer
  • Zend_Server
  • Zend_Service
  • Zend_Session
  • Zend_Soap
  • Zend_Tag
  • Zend_Test
  • Zend_Text
  • Zend_TimeSync
  • Zend_Tool
  • Zend_Tool_Framework
  • Zend_Tool_Project
  • Zend_Translate
  • Zend_Uri
  • Zend_Validate
  • Zend_Version
  • Zend_View
  • Zend_Wildfire
  • Zend_XmlRpc
  • ZendX_Console_Process_Unix
  • ZendX_JQuery
  • Translation 21.3% Update 2011-11-16 - Revision 24356 - Version ZF 1.11.x

    C.4. Styl kodowania

    C.4.1. Odgraniczanie kodu PHP

    Kod PHP musi być zawsze odgraniczony za pomocą pełnych, standardowych znaczników PHP:

    <?php

    ?>

    Użycie skróconej wersji znaczników jest niedozwolone. Pliki, które zawierają tylko kod PHP, nie powinny nigdy być zakończone znacznikiem zamykającym (Zobacz Sekcja C.2.1, „Ogólnie”).

    C.4.2. Łańcuchy znaków

    C.4.2.1. Proste łańcuchy znaków

    Kiedy łańcuch znaków jest prosty (nie zawiera podstawienia zmiennych), do jego odgraniczenia powinien zostać użyty pojedynczy cudzysłów (apostrof):

    $a 'Example String';

    C.4.2.2. Proste łańcuchy znaków zawierające apostrofy

    Kiedy prosty łańcuch znaków zawiera wewnątrz apostrofy, dozwolone jest odgraniczenie łańcucha za pomocą cudzysłowów (podwójnych). Jest to szczególnie przydatne w wyrażeniach SQL:

    $sql "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";

    Ta składnia jest zalecana w przeciwieństwie do zabezpieczenia apostrofów znakami ukośnika.

    C.4.2.3. Podstawienia zmiennych

    Podstawienia zmiennych są dozwolone na dwa sposoby:

    $greeting "Hello $name, welcome back!";

    $greeting "Hello {$name}, welcome back!";

    Dla zachowania spójności, taka forma jest niedozwolona:

    $greeting "Hello ${name}, welcome back!";

    C.4.2.4. Łączenie łańcuchów znaków

    Łańcuchy znaków mogą być łączone za pomocą operatora ".". Przed i za znakiem "." zawsze powinniśmy dodać znak odstępu:

    $company 'Zend' 'Technologies';

    Kiedy łączymy łańcuchy znaków za pomocą operatora ".", zalecane jest podzielenie wyrażenia na wiele linii w celu zwiększenia czytelności. W takich przypadkach, każda linia powinna być wcięta za pomocą znaków odstępu aby wszystkie operatory "." leżały w jednej linii pod znakiem "=":

    $sql "SELECT `id`, `name` FROM `people` "
         
    "WHERE `name` = 'Susan' "
         
    "ORDER BY `name` ASC ";

    C.4.3. Tablice

    C.4.3.1. Tablice indeksowane numerycznie

    Niedozwolone jest użycie ujemnych liczb jako indeksów tabel.

    Indeksowana tablica powinna zaczynać się od nieujemnej liczby, jednak liczby inne niż 0 jako pierwszy indeks są odradzane.

    Kiedy deklarujesz indeksowaną numerycznie tablicę za pomocą funkcji array, powinieneś dodać znak odstępu po każdym przecinku w celu zwiększenia czytelności:

    $sampleArray = array(123'Zend''Studio');

    Dozwolone jest deklarowanie tablic indeksowanych numerycznie w wielu wierszach używając konstrukcji "array". W takim przypadku, każdy następny wiersz musi być dopełniony, znakami odstępu aby początki wierszy były wyrównane:

    $sampleArray = array(123'Zend''Studio',
                         
    $a$b$c,
                         
    56.44$d500);

    C.4.3.2. Tablice asocjacyjne

    Kiedy deklarujesz tablice asocjacyjne za pomocą konstrukcji array zalecane jest rozbicie wyrażenia na wiele wierszy. W takim przypadku każdy następny wiersz powinien być dopełniony znakami odstępu, aby klucze i wartości były wyrównane:

    $sampleArray = array('firstKey'  => 'firstValue',
                         
    'secondKey' => 'secondValue');

    C.4.4. Klasy

    C.4.4.1. Deklaracja klas

    Klasy powinny być nazywane zgodnie z konwencjami Zend Framework.

    Klamra otwierająca klasę powinna zawsze znajdować się w linii pod nazwą klasy (styl "one true brace").

    Każda klasa musi posiadać blok dokumentacji zgodny ze standardem PHPDocumentor.

    Każdy kod wewnątrz klasy musi być wcięty na cztery spacje.

    Tylko jedna klasa dozwolona jest w jednym pliku PHP.

    Umieszczanie dodatkowego kodu w pliku klasy jest dozwolone, ale odradzane. W takich plikach dwie puste linie muszą oddzielać kod klasy od dodatkowego kodu PHP w pliku.

    Oto przykład poprawnej deklaracji klasy:

    /**
     * Blok dokumentacji
     */
    class SampleClass
    {
        
    // cała zawartość klasy musi
        // być wcięta na cztery spacje
    }

    C.4.4.2. Zmienne klas

    Zmienne klas powinny być nazywane zgodnie z poniższymi konwencjami.

    Wszystkie zmienne muszą być deklarowane na samym początku klasy, przed zadeklarowaniem jakichkolwiek funkcji.

    Użycie konstrukcji var jest niedozwolone. Zawsze deklarujemy widoczność zmiennych klas za pomocą jednej z konstrukcji: private, protected, lub public. Uzyskiwanie dostępu do zmiennych klas bezpośrednio poprzez ustawienie ich jako publicznych jest dozwolone, ale odradzane na rzecz metod dostępowych (set/get).

    C.4.5. Funkcje i metody

    C.4.5.1. Deklaracja funkcji oraz metod

    Funkcje powinny być nazywane zgodnie z poniższymi konwencjami.

    Funkcje wewnątrz klas zawsze muszą mieć zadeklarowaną dostępność za pomocą konstrukcji private, protected, lub public.

    Tak jak w klasach, klamra otwierająca powinna zawsze znajdować się w linii pod nazwą funkcji (styl "one true brace"). Nie powinno być odstępu między nazwą funkcji a otwierającym nawiasem argumentów.

    Deklarowanie funkcji w przestrzeni globalnej jest odradzane.

    Oto przykład poprawnej deklaracji funkcji w klasie:

    /**
     * Blok dokumentacji
     */
    class Foo
    {
        
    /**
         * Blok dokumentacji
         */
        
    public function bar()
        {
            
    // cała zawartość funkcji musi
            // być wcięta na cztery spacje
        
    }
    }

    UWAGA: Przekazywanie przez referencję dozwolone jest tylko podczas deklaracji funkcji:

    /**
     * Blok dokumentacji
     */
    class Foo
    {
        
    /**
         * Blok dokumentacji
         */
        
    public function bar(&amp;$baz)
        {}
    }

    Przekazywanie przez referencję podczas wywołania jest zabronione.

    Zwracana wartość nie może być objęta cudzysłowami. To mogłoby zmniejszyć czytelność kodu i może spowodować, że przestanie on działać, jeśli metoda w przyszłości będzie zwracać referencję.

    /**
     * Blok dokumentacji
     */
    class Foo
    {
        
    /**
         * ŹLE
         */
        
    public function bar()
        {
            return(
    $this->bar);
        }

        
    /**
         * DOBRZE
         */
        
    public function bar()
        {
            return 
    $this->bar;
        }
    }

    C.4.5.2. Użycie funkcji oraz metod

    Argumenty funkcji powinny być oddzielone jednym znakiem odstępu po przecinku. To jest przykład poprawnego wywołania funkcji przyjmującej trzy argumenty:

    threeArguments(123);

    Przekazywanie przez referencję w czasie wywołania jest zabronione. Zobacz sekcję opisującą sposób deklaracji funkcji, aby poznać prawidłowy sposób przekazywania argumentów przez referencję.

    Funkcje które przyjmują tablice jako argumenty, mogą zawierać konstrukcję "array" i mogą być rozdzielone na wiele linii w celu zwiększenia czytelności. W tych przypadkach wciąż obowiązuje standard dla tablic:

    threeArguments(array(123), 23);

    threeArguments(array(123'Zend''Studio',
                         
    $a$b$c,
                         
    56.44$d500), 23);

    C.4.6. Instrukcje kontrolne

    C.4.6.1. If/Else/Elseif

    Wyrażenia kontrolne oparte o konstrukcje if oraz elseif muszą posiadać jeden znak odstępu przed nawiasem otwierającym warunek i jeden znak odstępu za nawiasem zamykającym.

    Instrukcje warunkowe znajdujące się pomiędzy nawiasami muszą być odgraniczone znakami odstępu. Do grupowania większych warunków zalecane jest użycie dodatkowych nawiasów.

    Klamrowy nawias otwierający powinien znajdować się w tej samej linii co warunek. Nawias zamykający zawsze powinien znajdować się w osobnej nowej linii. Zawartość znajdująca się między nawiasami klamrowymi musi być wcięta za pomocą czterech znaków odstępu.

    if ($a != 2) {
        
    $a 2;
    }

    Formatowanie instrukcji "if", które zawierają instrukcję "elseif" lub "else", powinno wyglądać tak jak w poniższym przykładzie:

    if ($a != 2) {
        
    $a 2;
    } else {
        
    $a 7;
    }

    if (
    $a != 2) {
        
    $a 2;
    } elseif (
    $a == 3) {
        
    $a 4;
    } else {
        
    $a 7;
    }

    W pewnych okolicznościach PHP pozwala na zapisanie tych wyrażeń bez nawiasów. Standard kodowania wymaga, aby wszystkie wyrażenia "if", "elseif" oraz "else" używały nawiasów.

    Użycie instrukcji "elseif" jest dozwolone ale mocno odradzane. Zamiast tej instrukcji zalecane jest użycie kombinacji "else if".

    C.4.6.2. Instrukcja Switch

    Instrukcje kontrolne umieszczone wewnątrz instrukcji "switch" muszą posiadać pojedynczy znak odstępu zarówno przed nawiasem jak i za nim.

    Cała zawartość wewnątrz instrukcji "switch" musi być wcięta na cztery spacje. Zawartość każdej instrukcji "case" musi być wcięta na kolejne cztery spacje.

    switch ($numPeople) {
        case 
    1:
            break;

        case 
    2:
            break;

        default:
            break;
    }

    Konstrukcja default powinna zawsze znaleźć się wewnątrz konstrukcji switch.

    UWAGA: W niektórych przypadkach przydatne jest zapisanie jednej klauzuli case, po której sterowanie powinno przejść do następnej klauzuli case poprzez nie umieszczanie polecenia break lub return w wyjściowym case. Aby odróżnić takie sytuacje od niezamierzonych błędów, wszystkie instrukcje case których intencjonalnie pozbawiono break lub return muszą zawierać komentarz: "// break intentionally omitted".

    C.4.7. Dokumentacja

    C.4.7.1. Format dokumentacji

    Wszystkie bloki dokumentacji muszą być kompatybilne z formatem phpDocumentor. Opisywanie formatu phpDocumentor jest poza zakresem tego dokumentu. Aby uzyskać więcej informacji, odwiedź: http://phpdoc.org/

    Każdy plik źródłowy napisany dla Zend Framework lub działający w oparciu o framework musi posiadać na początku pliku ogólny blok dokumentacji dla danego pliku oraz blok dokumentacji dla klasy bezpośrednio przed jej deklaracją. Poniżej są przykłady takich bloków:

    C.4.7.2. Pliki

    Każdy plik zawierający kod PHP musi na samym początku posiadać blok dokumentacji zawierający przynajmniej następujące znaczniki standardu phpDocumentor:

    /**
     * Short description for file
     *
     * Long description for file (if any)...
     *
     * LICENSE: Some license information
     *
     * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
     * @license    http://framework.zend.com/license   BSD License
     * @version    $Id:$
     * @link       http://framework.zend.com/package/PackageName
     * @since      File available since Release 1.5.0
    */

    C.4.7.3. Klasy

    Każda klasa musi posiadać blok dokumentacji zawierający przynajmniej następujące znaczniki standardu phpDocumentor:

    /**
     * Short description for class
     *
     * Long description for class (if any)...
     *
     * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
     * @license    http://framework.zend.com/license   BSD License
     * @version    Release: @package_version@
     * @link       http://framework.zend.com/package/PackageName
     * @since      Class available since Release 1.5.0
     * @deprecated Class deprecated in Release 2.0.0
     */
     

    C.4.7.4. Funkcje

    Każda funkcja, a także metoda obiektu, musi posiadać blok dokumentacji zawierający przynajmniej następujące znaczniki standardu phpDocumentor:

    • Opis funkcji

    • Opis wszystkich argumentów

    • Opis wszystkich możliwych zwracanych wartości

    Nie jest konieczne użycie znacznika "@access" ponieważ poziom dostępu jest znany dzięki konstrukcji "public", "private", lub "protected" użytej podczas deklaracji funkcji.

    Jeśli funkcja/metoda może wyrzucać wyjątek, użyj znacznika "@throws":

    @throws exceptionclass [opis wyjątku]

    digg delicious meneame google twitter technorati facebook

    Comments

    Loading...