Wypracowaliśmy pewne zasady wg których budujemy nasze aplikacje i chcielibyśmy się nimi z Wami podzielić. Po co nam te zasady? Powodów jest wiele, kilka najważniejszych to:
- Szybsze tworzenie kodu zawierającego jednocześnie mniej błędów.
- Usprawnienie współpracy pomiędzy osobami zaangażowanymi w dany projekt (głównie programistami).
- Łatwiejsze "konserwowanie" kodu (rozwijanie, modyfikowanie, debugowanie itd.)
- Czytelny i zrozumiały (samodokumentujący się) kod pozwala też oszczędzić mnóstwo czasu i pracy jakiej wymaga prowadzenie dokumentacji projektu.
Wymienione poniżej zasady nie są jedynymi słusznymi. Po prostu dobrze sprawdzają się w naszej pracy, co nie znaczy że w uzasadnionych przypadkach nie stosujemy od nich pewnych odstępstw. Stale też ewoluują zmieniając się razem z nami w miarę jak sami się rozwijamy i zdobywamy większe doświadczenie.
Wszystkie zasady podzieliliśmy na kategorie, aby ułatwić Wam przeglądnięcie tych, które Was zainteresują:
I. Zasady ogólne
- Czytelny i zrozumiały kod (taki, aby nie wymagał komentowania).
- Nie duplikuj kodu.
- Minimalizm. Niech kodu będzie jak najmniej.
- Odpowiednio dobrane nazewnictwo (znaczące, opisowe, zgodne z pełnioną funkcją nazwy klas css, zmiennych, funkcji itd.)
II. CSS
-
Pojedynczy plik CSS.
W każdym projekcie cały kod CSS umieść w jednym pliku (np. style.css). Dodatkowe pliki stosuj tylko w uzasadnionych przypadkach, np. dla styli stron przeznaczonych do druku (np. druk.css). Dodatkowe pliki css dołączaj tylko kiedy są potrzebne.
Zerowanie styli
Zawsze zeruj style css (np. za pomocą poniższego kodu). Dzięki temu łatwiej będzie uzyskać te same efekty w różnych (także tych starszych) przeglądarkach.
Kliknij tutaj, aby zobaczyć przykład kodu zerującego-
Domyślne, wspólne style.
W każdym projekcie zdefiniuj wspólne style dla standardowych elementów html (takich jak np. h1, h2, p, table, a, itd.), które będą używane w całym serwisie.
Jeżeli raz dobrze zdefiniujesz domyślne wspólne style to wszystkie strony tworzone w czystym html od razu będą wyglądały jak należy (zawsze będziesz mógł dokonać dowolnych modyfikacji, zarówno lokalnie jak i globalnie). -
Formatowanie pliku ze stylami:
- kod pojedynczego tagu umieść w pojedynczej linii,
- atrybuty i wartości rozdziel spacjami,
- wyodrębnij bloki (np. zgodnie z podziałem na elementy lub podstrony) i jeżeli to konieczne (nazwy identyfikatorów i klas tego jednoznacznie nie mówią) opisz odpowiednim komentarzem.
/* menu */ #menu { background-color: #EEE; border: 1px solid blue } #menu li { color: #333; font-size: 18px } ... /* formularz kontaktowy */ #kontakt { display: block; float: left } #kontakt input { background-color: #aee; border: 1px solid #666 } ...Dzięki temu kod będzie bardziej czytelny. Łatwiej będzie odnaleźć interesujący nas fragment czy atrybut.
- Unikaj pozycjonowania "position: relative" i "position: absolute". Używaj go tylko w uzasadnionych przypadkach.
- Unikaj wyjątków dla IE.
- Nigdy nie używaj znacznika '!important'.
III. HTML
- Pliki koduj jako UTF-8 (chyba, że istnieje uzasadniony wyjątek).
- Jako deklarację typu dokumentu użyj Transitional DTD (chyba, że istnieje uzasadniony wyjątek):
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - Tabel używaj tylko dla danych tabelarycznych (ew. w uzasadnionych przypadkach).
- Testuj strony na bieżąco podczas tworzenia w różnych przeglądarkach - strona powinna wyglądać identycznie (w granicach rozsądku) w przeglądarkach: IE7 i nowszych, Firefox 3 i nowszych, Safari 4 i nowszych, Opera 9 i nowszych, Chrome 5 i nowszych.
-
Unikaj Divitis i Classitis - używaj jak najmniej znaczników HTML oraz
identyfikatorów i klas, aby kod był jak najmniejszy w stosunku do treści
merytorycznej serwisu np.:
zamiast: <div id="header"> <div class="bold">Heading</div> </div> <div id="subheader"> <div class="bold">Sub Heading</div> </div> <div>This is the content</div> użyj: <h1>Heading</h1> <h2>Sub Heading</h2> <p>This is the content</p> - Do efektów "rollover" (linków składających się z grafiki, których stan zmienia się w zależności od położenia myszki) używaj tak zwanych "sprites".
- Używaj znaczników semantycznych, a nie formatujących np. znacznika "<strong>" zamiast "<b>".
- Stosuj wcięcia w kodzie dla poprawienia czytelności (zalecane 4 spacje, zamiast 1 tabulatora)
- Jeżeli używasz do wypełnienia tekstu w stylu "Lorem ipsum dolor sit...", zawsze rozpocznij paragraf od "Lorem ipsum dolor sit amet...".
- Sprawdź, czy kod jest poprawny: http://validator.w3.org/
IV. Grafika
- Pliki graficzne segreguj w odpowiednich podkatalogach, np. pliki z nagłówka w katalogu "naglowek", butony w katalogu "butony".
- W przypadku kilku wersji językowych, jeżeli wystąpią oddzielne pliki graficzne, zapisuj je do odpowiednich podkatalogów np. "en", "pl".
- Używaj znaczących, opisowych nazw. W nazwach plików używaj tylko liter, cyfr i znaków "-", "_". Nie używaj polskich znaków ani spacji. Używaj tylko małych liter.
V. Javascript
- Javascript używany lokalnie np. pojedyncze funkcje (szczególnie jQuery) używane tylko w jednym widoku osadzaj w pliku razem z HTML tam, gdzie jest używany.
- Funkcje Javascript używane wielokrotnie w wielu miejscach umieść w osobnym pliku. W miarę możliwości używaj tylko jednego pliku i dołączaj go tylko kiedy jest potrzebny.
- Kompresuj pliki js. Zawsze zostaw nieskompresowaną wersję pliku (dobierz
odpowiednie nazwy plików dla jasności).
Przykładowe kompresory:
JSMin - http://crockford.com/javascript/jsmin
Dojo shrinksafe - http://dojotoolkit.org/docs/shrinksafe
Packer - http://dean.edwards.name/packer/
YUI Compressor - http://developer.yahoo.com/yui/compressor/
The JavaScript CompressorRater - http://compressorrater.thruhere.net/
VI. PHP
- Filtruj dane wejściowe - także pochodzące z plików cookie (np. aby zapobiec sql injection).
- Filtruj dane wyjściowe (aby zapobiec np. cross-site scripting).
- Dokumentuj swój kod (zgodnie z tagami phpDocumentor'a:
http://manual.phpdoc.org/HTMLframesConverter/default/).
Koniecznie podpisz się pod kodem w tagu @author. Przykład:
/** * Opis funkcji * @param int $param1 Opis parametru 1 * @param string $param2 Opis drugiego parametru * @return string opis zwracanej wartości * @author John Doe <john.doe@example.com> */ function somefunc($param1, $param2) { ... - Stosuj wcięcia w kodzie dla poprawienia czytelności (zalecane 4 spacje, zamiast 1 tabulatora).
- Nie zostawiaj zakomentowanych fragmentów kodu (jeżeli korzystasz z systemu kontroli wersji).
- Zawsze sprawdź czy Twój kod działa w niezależnym środowisku (każdy projekt powinien mieć specjalnie do tego celu stworzone środowisko testowe).
VII. MySQL
- Używaj kodowania UTF-8, chyba że istnieje uzasadniony przypadek, aby użyć innego.
- Tworząc tabelę zawsze wybierz dla niej optymalny typ, np. MyISAM gdy planujesz wyszukiwanie pełnotekstowe, InnoDB gdy tabela ma zawierać często aktualizowane dane.
- Jeżeli nazwa pola/kolumny nie opisuje jednoznacznie jego funkcji/zawartości, dołącz opis w komentarzu do tego pola/kolumny (COMMENT).
VIII. CakePHP
- Wszędzie gdzie to możliwe (i nie utrudnia pracy) trzymaj się konwencji.
- Przy zapisie do bazy za pomocą $this->ModelName->save() zawsze pamiętaj o użyciu opcji "fieldList". Szczególnie gdy zapisujesz dane z formularzy.
Powyżej wymienione zasady opracowaliśmy na podstawie własnych doświadczeń, ale także podpatrując sprawdzone standardy wg. których pracują inni. Oparliśmy się m.in. na:
- Robert C. Martin, "Czysty kod. Podręcznik dobrego programisty", Helion 2010. W oryginale: "Clean Code: A Handbook of Agile Software Craftsmanship.".
- Standardy kodowania PEAR: http://pear.php.net/manual/en/standards.php
- Standardy kodowania ZEND: http://framework.zend.com/wiki/display/ZFDEV/PHP+Coding+Standard+%28draft%29
- Standardy kodowania CakePHP:
https://trac.cakephp.org/wiki/Developement/CodingStandards
http://book.cakephp.org/view/509/Coding-Standards - Standardy kodowania Doctrine: http://www.doctrine-project.org/documentation/manual/1_0/nl/coding-standards
- Standardy kodowania Horde: http://www.horde.org/horde/docs/?f=CODING_STANDARDS.html
- http://net.tutsplus.com/tutorials/php/30-php-best-practices-for-beginners/
- http://manual.phpdoc.org/
- http://php.net/