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

Z Wikibooks, biblioteki wolnych podręczników.

Poprzedni rozdział: Inne:Autorzy

Spis treści

Spis treści 1 Dla twórców podręcznika 1.1 Oprogramowanie 1.2 Nawigacja 1.3 Styl 1.4 Neutralny punkt widzenia 1.5 Podstrony 1.6 Szablony

[edytuj] 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.

[edytuj] Oprogramowanie

Wszystkie informacje powinny być w miarę aktualne i dotyczyć przynajmniej PHP 5.1 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.

[edytuj] 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.

[edytuj] 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.

1. Nawiasy klamrowe otwieramy w nowej linijce
2. Wcięcia trójznakowe
3. W nazewnictwie posługujemy się camelStyle (tj. zmienne, funkcje itd. nazywamy jako nazwaFunkcji, a nie nazwa_funkcji albo nazwafunkcji).
4. Poszczególne części algorytmu staramy się separować linijką przerwy
5. Kod musi być skomentowany, najlepiej komentarzami jednolinijkowymi

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

1. 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.
2. Wszystkie zmienne wcześniej inicjujemy.
3. W programowaniu obiektowym każdą metodę poprzedzamy przedrostkiem public, private itd.
4. Nie stosujemy elementów składni typowych dla PHP 4 (np. var), chyba że w opisach objaśniających różnice między wersjami.
5. Konstrukcje używane niezgodnie z przeznaczeniem powinny być omijane. Zaliczają się do nich m.in. funkcja("$zmienna");

[edytuj] 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.

[edytuj] Podstrony

• Do zrobienia
• Wytyczne dla rozdziałów (czyli co każdy powinien zawierać)

[edytuj] Szablony

Oto wykaz szablonów używanych w podręczniku:

Opis	Kod	Efekt
Ostrzeżenie czytelnika	{{Uwaga|Tekst ostrzeżenia}}	Uwaga! Tekst ostrzeżenia
Porada	{{Porada|Tekst porady}}	Porada Tekst porady
Informacja	{{Infobox|Tekst informacji}}	Tekst informacji
Definicja	{{Definicja|Tekst definicji}}	Tekst definicji
Do zrobienia	{{TODO|co zrobić}}	Do zrobienia: co zrobić
Do zrobienia do wstawiania w sekcji stosować tylko w rozdziałach, w których większość tekstu jest napisana	{{RDoZrobienia}}	Ta sekcja jest zalążkiem. Jeśli możesz, rozbuduj ją
Artykuł do poprawy	{{poprawić|powód}}	Ten artykuł został uznany przez jednego z wikipedystów za wymagający dopracowania z następującego powodu: "powód". Jeśli możesz, popraw go. Przydatne wskazówki mogą znajdować się na stronie dyskusji tego artykułu.