PHP/Inne/Dla twórców podręcznika

Poprzedni rozdział: Autorzy

Dla twórców podręcznika

Niniejsza strona zbiera zalecenia dla autorów i standardy, w jakich pisany będzie podręcznik. Wszelkie uwagi i propozycje powinny być dyskutowane na stronie dyskusji.

Oprogramowanie

Wszystkie informacje powinny być w miarę aktualne i dotyczyć przynajmniej PHP 5.2/5.3 oraz MySQL 5.0. Biblioteki programistyczne opisujemy również w oparciu o ostatnią wersję.

Jeżeli chcesz opisać jakąś bibliotekę, zgłoś to w dyskusji i zaproponuj spis treści. Wykaz propozycji można znaleźć na podstronie Do zrobienia.

Nawigacja

Na górze każdej podstrony prosimy zamieszczać następujący szablon:

Poprzedni rozdział: poprzedni

Spis treści

Następny rozdział: nastepny

którego kod jest następujący:

 {{subst:naw|PHP|poprzedni|nastepny}}

Pola poprzedni oraz nastepny wypełniamy nazwami odpowiednich rozdziałów. Spis treści dostępny jest na stronie głównej podręcznika i wszelkie ważniejsze edycje należy uprzednio konsultować w dyskusji.

Styl

Podręcznik ten nie ma przypominać pracy zaliczeniowej ze studiów, ale dawać czytelnikowi możliwość zrozumienia czegoś. Nie unikajmy zatem przykładów, nawet tych banalnych oraz niekoniecznie związanych z programowaniem i często wracajmy do omówionych już wcześniej spraw. Definicje muszą być opatrzone konkretnym przykładem lub wyjaśnieniem, po co taka rzecz istnieje. Co jakiś czas tekst zachęca do samodzielnych eksperymentów i pokazuje, jak się za nie można zabrać. Wskazane są przydatne miejsca, adresy, techniki analizy kodu.

Myślą przewodnią niniejszego podręcznika jest tzw. zasada złotego środka. Czytelnik po przeczytaniu powinien mieć wyrobiony nawyk pytania siebie, czy dana rzecz jest mu rzeczywiście potrzebna w oryginalnym kształcie. Wszystkie zagadnienia powinny mieć czytelnie wyszczególnione wady oraz zalety bez dołączanych twierdzeń sugerujących, że jest to panaceum na wszystkie problemy świata.

Bardzo ważne jest graficzne rozłożenie tekstu na stronie, aby nie sprawiał wrażenia chaotycznego. Podczas edycji zawsze możemy podejrzeć, jak wprowadzone zmiany będą się prezentować. Unikajmy za wszelką cenę jednozdaniowych akapitów oraz nieracjonalnego dzielenia nimi jednolitej treści. Wskazane jest stosowanie list wypunktowanych lub numerowanych. Są bardziej przejrzyste niż normalny tekst, a przy tym zwięzłe. Używaj też ramek pomocniczych, których spis został zamieszczony niżej.

Przykładowe kody źródłowe muszą być napisane czytelnie, w oparciu o identyczne formatowanie.

Nawiasy klamrowe otwieramy w nowej linijce.
Wcięcia trójznakowe.
W nazewnictwie posługujemy się camelStyle (tj. zmienne, funkcje itd. nazywamy jako nazwaFunkcji, a nie nazwa_funkcji albo nazwafunkcji).
Poszczególne części algorytmu staramy się separować linijką przerwy.
Kod musi być skomentowany, najlepiej komentarzami jednolinijkowymi.
Na końcu skryptu nie wstawiamy znaku ?>

W kodach źródłowych staramy się unikać nieprawidłowych nawyków:

Niepotrzebne zmienne tymczasowe - jeżeli są potrzebne, wyjaśniamy dlaczego. Pamiętajmy o tym szczególnie przy omawianiu baz danych, gdzie zapytania piszemy bezpośrednio w funkcji/metodzie, bez żadnej pomocniczej zmiennej $query, $zapytanie itd.
Wszystkie zmienne wcześniej inicjujemy.
W programowaniu obiektowym każdą metodę poprzedzamy przedrostkiem public, private itd.
Nie stosujemy elementów składni typowych dla PHP 4 (np. var), chyba że w opisach objaśniających różnice między wersjami.
Konstrukcje używane niezgodnie z przeznaczeniem powinny być omijane. Zaliczają się do nich m.in. funkcja("$zmienna");

Kod musi być zawarty w znacznikach <syntaxhighlight lang="php"> ... </syntaxhighlight>, np.

<?php
echo 'Hello world';

Neutralny punkt widzenia

Zgodnie z zasadą Wikibooks, podręcznik powinien utrzymany być w konwencji ***neutralnego punktu widzenia***. Dotyczy to w szczególności takich rozdziałów, jak Edytory PHP czy Pomoc, które wcale nie służą do reklamowania własnych aplikacji bądź serwisów WWW. Wszelkie kontrowersyjne materiały będą usuwane albo przeredagowane bardzo szybko.

Dobór bibliotek

W podręczniku, oprócz PHP, omawiane są też wybrane biblioteki programistyczne stworzone w tym języku. Ponieważ bibliotek jest dużo, a tylko niektóre z nich trzymają odpowiedni poziom, utworzony został zbiór warunków, jakie biblioteka musi spełnić, aby mogła być omówiona w podręczniku w trosce o jego jakość.

Obecność infrastruktury internetowej - system kontroli wersji, bugtracker, forum dla użytkowników
Przynajmniej rok aktywnego rozwoju - w ciągu roku od pojawienia się podręcznika biblioteka musi być cały czas aktywnie rozwijana (nowe wersje, poprawianie błędów, nowa funkcjonalność). Podstawą jest aktywność w repozytorium SVN lub innego systemu kontroli wersji.
Dostępne wydanie stabilne - biblioteka musi mieć przynajmniej jedno wydanie stabilne (tzw. wersja 1.0) aby mogła być umieszczona w podręczniku
Dostępna kompletna dokumentacja - biblioteki bez dokumentacji lub jedynie ze szczątkową dokumentacją (np. wygenerowany minimalistyczny APIDoc) nie mogą być umieszczone w podręczniku.
Wsparcie dla PHP 5.2/PHP 5.3 - biblioteka musi bezproblemowo pracować na podanych wersjach PHP.
Konsultacja na stronie dyskusji podręcznika

Pamiętaj, że podręcznik przede wszystkim poświęcony jest PHP. Rozdziały o bibliotekach mają jedynie pokazać zagadnienie i służyć za wstęp do danego tematu. Pełne omówienie biblioteki wykracza poza ramy tego podręcznika.