Styl kodowania i standardy

Uwaga o zawartości

Ta strona wymaga przetłumaczenia lub jest w trakcie tłumaczenia! Pomoc jest mile widziana. Ostatnio edytowane przez Zwiastun (dyskusja. Data edycji: Fri, 06 Dec 2013 00:42:30 +0000

remark: The following information has been copied from the old WIKI archive has not yet been reviewed. See: http://dev.joomla.org/component/option,com_jd-wiki/Itemid,/id,standards:coding/

Good coding standards are important in any development project, but particularly when multiple developers are working on the same project. Having coding standards helps ensure that the code is of high quality, has fewer bugs, and is easily maintained.

Standardy pisania kodu

Wcięcia i długość linii

Do wykonania wcięcia używaj tabulatora zamiast spacji. Upewnij się, że szerokość tabulatora jest ustawiona na maximum 4 znaki. Zaleca się, aby linia nie była dłuższa niż 75-85 znaków. Nie ma konkretnych standardów określających długość linii. Sam oceń, jaka długość jest dla Ciebie najwygodniejsza.

Instrukcje warunkowe

Są to if, for, while, switch, itp. Tu jest przykład instrukcji if. Jest no najbardziej skomplikowana instrukcja warunkowa:

<?php
if ((warunek1) || (warunek2)) {
    action1();
} elseif ((warunek3) && (warunek4)) {
    action2();
} else
{
    domyslnezadanie();
    kolejnezadanie();
}
?>

Instrukcje warunkowe powinny posiadać spację przed słowem instrukcji i po nim, by odróżniały się od wywołań funkcji.

Zalecane jest używanie nawiasów klamrowych "{}" zawsze, nawet jeśli nie jest to potrzebne. Poprawiają one czytelność i zapobiegają błędom logicznym, które mogą się pojawić podczas dodawania nowych wierszy.

Dla instrukcji switch:

<?php
switch (warunek)
{
    case 1:
        akcja1();
        break;
 
    case 2:
        akcja2();
        break;
 
    default:
        domyslnaakcja();
        break;
}
?>

Wywołania funkcji

Funkcje winny być wywoływane bez spacji pomiędzy nazwą funkcji a nawiasem zawierającym jej zmienne, jedna spacja przed pierwszym parametrem; spacja po każdym przecinku, i jedna spacja po ostatnim parametrze, bez spacji po nawiasie a przed średnikiem. Oto przykład:

<?php
$var = foo( $bar, $baz, $quux );

Jak powyżej, zarówno przed, jak i po znaku równości powinna być jedna spacja. W przypadku bloku kilku przypisań zmiennych dobrze jest użyć przed znakiem równania tabulatora. Poprawi to czytelność kodu tak jak w tym przypadku:

<?php
$short         = foo( $bar );
$long_variable = foo( $baz );

Definiowanie funkcji

Przy definiowaniu klas i funkcji powinieneś trzymać się jedynej słusznej konwencji:

<?php
function fooFunction( $arg1, $arg2 = '' )
{
    if (condition) {
        statement;
    }
    return $val;
}
 
class fooClass
{
    function fooMethod( $arg1 )
    {
        if ($arg) {
            $result = true;
        } else {
            $result = false;
        }
        return $result;
    }
}

Argumenty z ustawionymi wartościami domyślnymi powinny znajdować się na końcu list argumentów. Jeśli jest to możliwe zawsze staraj się zwrócić jak najbardziej jednoznaczną wartość z funkcji. Tu jest nieco dłuższy przykład:

<?php
function connect( &$dsn, $persistent = false )
{
    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }
 
    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }
 
    return true;
}

Komentarze

Dokumentacja w kodzie dla klas powinna stosować się do konwencji PHPDoc podobnej do Javadoc. Więcej inforamcji o PHPDoc można znaleźć na stronie http://www.phpdoc.org/

Zobacz także Adding phpDocumentor comments

Poza dokumentacją zalecane jest stosowanie nie-dokumentacyjnych komentarzy. Generalnie, jeśli patrzysz na fragment kodu i myślisz sobie "Wow, nie chce mi się nawet próbować tego komentować", powinieneś to skomentować zanim zapomnisz jak to działa.

Komentarze w stylu C (/* */) i C++ (//) są w porządku. Niemile widziane jest natomiast stosowanie komentarzy w stylu Perl/Shell tzn. (#)

Dołączanie kodu

Wszędzie, gdzie bezwarunkowo dodajesz plik z deklaracją klasy, używaj require_once(). Wszędzie, gdzie warunkowo dodajesz plik z deklaracją klasy, używaj include_once(). Obie z tych dyrektyw zapewniają, że klasy zostaną dodane tylko raz. Współdzielą one tę samą listę plików tak, że nie musisz się martwić o dodawanie obydwu za każdym razem - plik dodany przez require_once() nie będzie dołączony kolejny raz przez include_once().

Informacja

include_once i require_once są dyrektywami języka, a nie funkcjami. Nie musisz się więc martwić o dodawanie nawiasu wokół nazwy dołączanego pliku.

Tagi kodu PHP

Zawsze używaj <?php ?>, żeby określić kod PHP zamiast skróconego <? ?>. To najbardziej uniwersalna metoda by dodać kod PHP na różnych systemach i w różnych konfiguracjach.

Dla plików, które zawierają tylko kod PHP, tag zamykający (?>) nie jest potrzebny. PHP go nie wymaga. Niedodawanie go zapobiega wkradaniu się w kod wynikowy zbędnych i nieprzewidzianych spacji.

Zapytania SQL

Wszystkie słowa kluczowe SQL powinny być pisane dużymi literami, natomiast wszystkie inne wyrażenia (oczywiście poza tekstami wstawianymi w cydzysłowach ) powinny być pisane małymi literami. Carriage returns should not be used as JDatabase::getQuery provides for formatted output. Jednakże wcięcia przy pomocy spacji mające na celu poprawienie czytelności są wskazane. However, indenting with spaces to improve readability is desireable.

Zapytania do bazy powinny być zapisane jako pojedynczy cudzysłów (jako tekst są szybciej parsowane przez PHP).

Wszystkie teksty ujęte w cydzysłowie powinny korzystać z metody Quote by umożliwić kompatybilność z różnymi silnikami baz danych.

Wszystkie nazwy tabel powinny używać prefiksu #_ zamiast jos_ aby użytkownik mógł ustawić własne prefiksy baz danych.

Wszystkie zmienne, które oczekujesz, że będą liczbami całkowitymi lub zmienno-przecinkowymi powinny być rzutowane poprzez (int), (float) lub (double) adekwatnie do typu zmiennej.

$state = 1;
$name  = 'bill';
$db    = &JFactory::getDBO();
$query = 'SELECT COUNT( c.id ) AS num_articles, u.id, u.username'.
    ' FROM #__content AS c'.
    ' LEFT JOIN #__users AS u ON u.id = c.created_by'.
    ' WHERE c.state = '.(int) $state
    '  AND u.id IS NOT NULL'.
    '  AND u.username <> '.$db->Quote( $name ).
    ' GROUP BY u.id'.
    '  HAVING COUNT( c.id ) > 0';
$db->setQuery();
// wyświetl sformatowane zapytanie
if ($debug) {
    echo $db->getQuery();
}
$stats = $db->loadObjectList();

Komentarze w nagłówku

Wszystkie pliki źródłowe powinny zawierać następujące komentarze:

<?php
 
/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
 
/**
 * Krótki opis pliku
 *
 * Długi opis pliku
 *
 * Docelowe wersje PHP
 *
 * LICENCJA: Ten plik jest częścią Licencji PHP dostępnej w internecie 
 * pod następującym adresem: http://www.php.net/license/3_0.txt. Jeśli nie
 * otrzymałeś licencji PHP i nie możesz jej znaleźć na powyższej stronie
 * napisz na adres license@php.net. Wyślemy Ci natychmiast kopię.
 *
 * @category   Nazwa kategorii
 * @package    Nazwa paczki
 * @author     Oryginalny autor <author@example.com>
 * @author     Kolejny autor <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id:$
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      Plik dostępny począwszy od wersji 1.2.0
 * @deprecated Porzucony począwszy od wersji 2.0.0
 */
 
/*
 * Place includes, constant defines and $_GLOBAL settings here.
 * Make sure they have appropriate docblocks to avoid phpDocumentor
 * construing they are documented by the page-level docblock.
 */
 
/**
 * Krótki opis klasy
 *
 * Długi opis klasy
 *
 * @category   Nazwa kategorii
 * @package    Nazwa paczki
 * @author     Oryginalny autor <author@example.com>
 * @author     Kolejny autor <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    Release: @package_version@
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      Klasa dostępna począwszy od wersji 1.2.0
 * @deprecated Klasa porzucona począwszy od wersji 2.0.0
 */
class foo
{
}

Nie ma dokładnej reguły kiedy nowy autor kodu powinien zostać dodany do pliku źródłowego. Ogólnie wniesione przez niego zmiany powinny być minimum 10-20% całości kodu. Wyjątkami mogą być momenty kiedy przepisane od nowa zostały jakieś funkcje lub przebudowana została logika kodu.

Zwykła reorganizacja kodu lub naprawa błędu nie powinna determinować dodania do listy autorów

Pliki które nie należą do jądra Joomla! powinny zawierać podobne bloki zaczynając od Praw autorskich, poprzez licencję i autorów. Wszystkie pliki powinny zawierać komentarze by uniknąć bałaganu.

Przykładowe adresy

Używaj "example.com", "example.org" and "example.net" dla wszystkich przykładowych adresów stron lub e-mail.

Konwencje nazw

Klasy

Klasom powinieneś nadawać opisowe nazwy. Unikaj używania skrótów, jeśli to możliwe. Nazwy klas zawsze powinny zaczynać się od dużej litery.

Functions and Methods

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). Functions should in addition have the package name as a prefix, to avoid name collisions between packages. The initial letter of the name (after the prefix) is lowercase, and each letter that starts a new "word" is capitalized. Some examples:

connect()
getData()
buildSomeWidget()
XML_RPC_serializeData()

Private class members (meaning class members that are intented to be used only from within the same class in which they are declared; PHP4 does not support truly-enforceable private namespaces) are preceded by a single underscore. For example:

_sort()
_initTree()
$this->_status

Stałe

Stałe zawsze powinny być pisane dużymi literami oddzielając wyrazy dolną kreską (_) zamiast spacją. Nazwy zmiennych poprzedzać powinien prefix klasy bądź paczki w której są używane. Przykładowo stałe używane w klasie JError powinny się zaczynać od "JERROR_" więc nazwa stałej wyglądała by tak: "JERROR_NAZWASTALEJ"

Zmienne globalne

Jeśli twoja paczka wymaga zdefiniowania zmiennych globalnych, ich nazwy powinny zaczynać się od dolnej kreski (_), po niej powinna nastąpić nazwa paczki, następnie znów dolna kreska (_) oraz nazwa zmiennej. Dla przykładu zmienna globalna w klasie JError wylgądała by tak: $_JERROR_LEVELS

Od PHP5 począwszy możesz używać zmienny chstatycznych bądź stałych zamiast zmiennych globalnych.

<?php
class JKlasa
{
public static $instance = null;
const SUCCESS = 1;
const FAILURE = 0;
   //metody
}

Controller (Kontroler)

Dla komponentów zawierających jeden kontroler, nazwa klasy kontrolera powinna wyglądać tak: [nazwakomponentu]Controller.

<?php
/**
 * Mojkomponent Controller
 * @package Joomla
 */
class MojkomponentController extends JController
{
    // Metody
}
?>

Nazwa pliku powinna wyglądać tak: 'controller.php' i znajdować się w katalogu głównym komponentu.

com_mojkomponent/
 /controller.php

Dla komponentów zawierających wiele kontrolerów, jak np. komponent Banners nazwy klasy kontrolera powinny wyglądać tak: [nazwakomponentu]Controller[nazwakontrolera]

<?php
/**
 * Banner Client Controller
 * @package Joomla
 */
class BannerControllerClient extends JController
{
    // metody
}
?>

Pliki kontrolerów znajdować powinny się w katalogu /controllers/ w katalogu głównym komponentu. A nazwy plików powinny odpowiadać nazwie kontrolera.

com_banner
  /controllers/
    / banner.php
    / client.php

Modele (Models)

Nazwy klas modeli powinny trzymać się tej reguły: [nazwakomponentu]Model[nazwamodelu]

<?php
/**
 * Banner Client Model
 * @package Joomla
 */
class BannerModelClient extends JModel
{
    // Metody
}
?>

Pliki modelów powinny znajdować się w katalogu /models/ w głównym katalogu komponentu. Nazwy plików powinny odpowiadać nazwom modelów.

com_banner
  /models/
    / banner.php
    / client.php

Widoki (Views)

Nazwy klas widoków powinny trzymać się reguły: [nazwakomponentu]View[nazwawidoku]

<?php
/**
 * Contact Category View
 * @package Joomla
 */
class ContactViewCategory extends JView
{
    //metody
}
?>

Pliki widoków powinny znajdować się w katalogach, których nazwa jest nazwą danego widoku, oraz które znajdują się w katalogu /view/ w głównym katalogu komponentu.

com_mojkomponent
 /views/
   /nazwawidoku1/
     / view.html.php
   /nazwawidoku2/
     / view.html.php

Komponenty zawierające wiele widoków mogą posiadać widok "główny/nadrzędny", który jest prototypem dla innych widoków. Powinien znajdować się on w katalogu /view/ i nazwa pliku powinna wyglądać tak: view.php. Nazwa klasy natomiast powinna trzymać się reguły: [nazwakomponentu]View.

com_content
 /views/
    /archive/
      / view.html.php
    /article/
 / view.php

view.php
<?php
/**
 * Content View
 * @package Joomla
 */
class ContentView extends JView
{
    // metody klasy nadrzędnej
}
?>
 
views/archive/view.html.php
<?php
/**
 * Content Archive View
 * @package Joomla
 */
class ContactViewArchive extends ContentView
{
    // metody
}
?>

Szablony (Layouts)

Komponent może obsługiwać wiele szablonów, które zaprezentują dane przesłane przez widok (View) z modelu (Model). Szablon powinien zawierać jak najmniej kodu PHP. Żadnych klas i funkcji. Pozwala to na oddzielenie kodu PHP od HTML i ułatwia wszelkie zmiany w budowie.

Szablon zawierać powinien co najmniej jeden plik .php i odpowiadający mu nazwą plik .xml. Wszystkie szablony powinny znajdować się w katalogu /tmpl/ umieszczonym w katalogu danego widoku (view). Standardowy szablon nazywa się 'default'

com_content
  /views/
    /article/
      /tmpl/
        / default.php
        / default.xml
        / form.php
        / form.xml
        / pagebreak.php
        / pagebreak.xml

Szablon może używać innego szablonu w celu pokazania treści powtarzających się w kilku miejscach lub szablonach.

Użytkownicy mogą używać własnych szablonów, zastępując tym samym szablony komponentu. Stosuje się w tym celu tzw. Przesłanianie szablonów

Przesłanianie szablonów

Dziękujemy za wkład

» Stefan Wajda [zwiastun],