PHP/Inne/Dla twórców podręcznika: Różnice pomiędzy wersjami

Usunięta treść Dodana treść
Zyx (dyskusja | edycje)
poprawka nawigacji + wytyczne dot. doboru bibliotek
Linia 23:
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.
Linia 29:
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 <code><nowiki>?></nowiki></code>
 
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 <code><nowiki><source lang="php"> ... </source></nowiki></code>, np.