Dobrze, że poruszasz temat dokumentacji i jej tworzenia, ale niestety z własnego doświadczenia wiem jak to wygląda w małych firmach i/lub u początkujących programistów. Wyskoczenie z IDE typu fajny (ale niestety płatny) phpStorm czy NetBeans lub Eclipse to już dla części komplrtna abstrakcja. Podpowiadanie składni nic nie da, jeśli zwłaszcza w tej ostatniej grupie kuleją podstawy znajomości języka. Wiele osób myśli, że skoro umieją napisać prostą stronkę w html, to są już webmasterzy pełną gębą. A potem taki ma problem i nawet nie wie o co w wyszukiwarce zapytać, a na hasło "Masz to w dokumentacji/google" reagują alergią bo "przecież oni są masterzy" ;) Jeśli nie rozumiesz o co mi chodzi to wejdź na takie forum jak forum.php.pl i poprzeglądaj jake tam tematy lądują a się załamiesz. Przykłady najświeższe: użytkownik pyta "Czy można w jednym formularzu użyć POST i GET jednocześnie?", "Jak wyświetlić wyniki z bazy w formie tabelki?", a to tylko najświeższe spośród tych, gdzie użytkownicy mają elementarne luki.

Dobrze, że starasz sie pokazać jak można sobie upraszczać życie oraz pracującym potem z Twoim kodem, ale widzę, że chcesz wiedzę przekazywać nie tylko tym już nieco grzebiącym się, więc chyba brakuje całości jeszcze jednego artykułu pomiędzy Twoimi: "Skąd czerpać wiedzę?". Na nic bowiem świetne IDE z wsparciem dla języka, dobrze udokumentowany kod, jeśli sam użytkownik niekumaty. Posadzenie go przed dokumentacją bardzo nawet prosto złożoną to będzie dlań kara i nic on z niej nie zrozumie.

A teraz coś od siebie. Jeśli już zacząłeś cykl o dokumentowaniu z użyciem takich narzędzi jak phpDoc i może trzeba by dorzucić coś, co i bez tego pozwala się "znaleźć" w kodzie innych programistów - konwencje programistyczne. Jak parować nawiasy, jak nazywać zmienne i cała ta otoczka, która sprawia, że nie zawsze phpDoc w przypadku małych projektów jest konieczny.

Inna rzecz o której można by w kolejnych artykułach wspomnieć to wyszukiwanie i analiza błędów. Nieraz pomagam innym i stąd pisanie po raz X "włącz wyświetlanie błedów, zarzuć logami, podaj komunikaty błędów" jest czasem irytujące gdy sie po raz Y słyszy: "Ale jak mam to zrobić?". Dlatego jeden z artykułów możesznapisać o narzędziach takich jak FireBug, FirePHP, xDebug i choćby własnych error_handlerach :)

Gdy już jesteśmy z kolei przy aplikacjach to na nic świetna aplikacja skoro dziurawa. A ile osób słyszało o testach automatycznych? PHPUnit się kłania tutaj. I jak już mamy debug oraz testowanie to można by wspomnieć o tym jak choćby na proste sposoby się zabezpieczać przed sql injection i podobnymi atakami. Wiele osób zna pojęcia, ale jak ślepi znają rozwiązania, które nie zawsze są prawidłowe. Sam nieraz słyszałem mantrę "używam addslashes, więc to mi sql injection nie grozi" czy "przed wysłaniem do bazy używam addslashes i htmlspecialchars", w sytuacji gdy uzycie tej pierwszej jest zwyczajnie bezsensowne :) Można więc rozwinąć temat głównych typów ataków i form przeciwdziałania im.

Myślę, że coś z tego może Ci się do następnych artykułów przydać jako temat. A sam artykuł prosty i czytelny. Oby tak dalej :) Jeszcze trochę i chyba jedyne sensowne artykuły będziesz jako jeden z niewielu pisał tutaj :D

Mały błąd mi się wkradł. Używanie drugiej funkcji, czyli htmlspecialchars, jest przy wstawianiu do bazy bezsensowne. Ona słuzy do innych celów i są one już przy wyświetlaniu istotne, a nie zapisie...

Dzięki Thek za obszerny komentarz. Moje ale:
1. Mówisz o PHPUnit gdzie wcześniej mi pisałeś że ludzie boją się dokumentacji. PHPUnit wymaga albo napisania testów pod aplikacje albo tworzenie kodu który da się przetestować istniejącymi narzędziami.
2. Nie wiem czy będę poruszał tematy związane z bezpieczeństwem. Już samo XSS można "streścić" na 2-3 artykułach. Teksty moje dotychczas troszkę zajmowały i mam niestety odgórny limit co do długości takiego.
3. Debugowanie kodu owszem. Będzie i o tym w przyszłości. Jak będę miał więcej czasu to może i o profilowaniu coś powstanie.
4. W konwencje to ja bym się specjalnie nie mieszał. Każdy stosuje swoje i stara się udowodnić że jego jest najlepsza. Gdzie prawda jest taka że zespół po prostu powinien ustalić jakiś standard nazewnictwa i się tego trzymać. Jak ma sens to jest dobry. Ale się pomyśli.
5. Jeżeli chodzi o phpStorm, Eclipse, Netbeans i inne narzędzia to one wszystkie radzą sobie z kodem lepiej lub gorzej. Akurat z phpStorm korzystam na co dzień, zarówno w pracy jak i w domu więc na jego przykładzie pokazałem różne sytuacje. Inne IDE też sobie radzą spokojnie.
6. Zauważ że tekst jest przestrogą dla tych którzy kodu nie dokumentują. Wątpię żeby nad jakimś projektem pracowała banda ludzi którzy nic nie umieją :P Na ogół jest to banda ludzi którzy umieją sporo ale są zbyt leniwi (i nie widzą sensu) w napisaniu paru linijek komentarzy do kodu. Zwłaszcza że wiele IDE napisze Ci 70% komentarzy jak dasz /** i ENTER. Tobie zostaje dodać opis.

"Przykłady najświeższe: użytkownik pyta "Czy można w jednym formularzu użyć POST i GET jednocześnie?""

Czemu uważasz to za głupie pytanie? Odpowiedź jest twierdząca, można. W action podajesz argumenty do wysłania metodą GET, a pozostałe dane z formularza wysyłasz przez method POST.

Jak już to podawaj jakieś lepsze przykłady, MASTA :)

@Dariusz P.
ad 1) Owszem, ale widzę, że piszesz artykuły tak, by i mniej i lepiej obeznani coś wyciągnęli. Samo pokazanie, że mozna zrobić coś "z automatu" może ich zachęcic do poznania narzędzia. PhpDoc też nim "tylko" przecież jest ;)

ad 2) O limicie wiem, zdążyłeś mnie o nim poinformować w poprzednich artykułach. Co do XSS to nie mówie o zabezpieczeniach przeciwko wymyślnym atakom, ale wytłumaczeniu co to tak naprawdę jest i jak można unikać najprostszych błędów, a więc jak powinna wyglądać prawidłowa walidacja wejścia, co to jest bindowanie parametrów do zapytań.

ad 3) Chętnie poczytam gdy sie ukaże :)

ad 4) To prawda, ale można pokazać kilka najpopularniejszych, tak by wiedzieli na czym się wzorować, bo każdy język z reguły ma własne "domyślne", które stosuje ogół programistów. Jeśli chodzi o nazewnictwo zmiennych, w php do takiego pretenduje "underscore", w JS camelCase. Poza tym kilka typów zamknięć mozna opisać. Czasem bowiem widząc kod bez wcięć i z byle jak dawanymi nawiasami to się nóż otwiera ;)

ad 5) Można by się więc pokusić o streszczenie tych IDE i pokazanie ich możliwości, bez oceniania, bo to nie ma sensu. I tak każdy wybierze mu bardziej pasujące.

ad 6) To prawda. Ja należę do grupy bezIDEowców (preferuję pisanie w Notepad++ opluginowanym bo mały, szybki i ma tylko to co mi trzeba), ale mam czytelny kod i w sumie uważam, że konwencje przeze mnie przyjęte sprawiają, iż tylko nietypowe fragmenty komentować muszę. Reszta jest zbyt czytelna.

@markac: Co nie znaczy, że jest to rzecz trudna i ukrywana przez kogokolwiek. Poza tym jeśli ktoś już pisze kod formularza to po jakiego grzyba ma mieszać GET i POST, skoro może to co ma w GET posłać jako pole hidden formularza? Kod od razu zyskuje na czytelności i prostocie obsługi :) Poza tym GET przez długi czas miał ogromne ograniczenia (256 znaków) i w sumie nawet teraz nie wszystkie przeglądarki akceptuja tak długie url, tak więc POST dodatkowo ma zaletę większej niezawodności.

@thek,
Zastanawiam się czy nie rozwinąć tematu phpDoc opisując w całości jakie daje możliwości. Przy okazji temat przyda się wszystkim w sumie.

apropo ad2, myślałem że takie podstawy o których mówisz pokrywa ten tekst: https://di.co(...)ty.html. Zresztą sam go komentowałeś :P

4. Będę to trzymał w pamięci.

5. Dlatego też w ogóle o IDE nie pisałem. Te które w ogóle warto wziąć pod uwagę dużo się między sobą nie różnią. Jeden ma jakieś drobiazgi których drugi nie ma i vice versa. Nie mówiąc o tym że na samym Eclipse powstało kilka produktów, nie tylko do PHP. Jest jeszcze cały temat wtyczek. Opisywać możliwości IDE bez wtyczek to jak porównywać możliwości gołego Firefoxa do np Opery.

6. Owszem, ale tu chodzi o czystą produkcję. W momencie jak pisze, nie chce mi się sprawdzać kilkaset linii wyżej jaki obiekt jest w jakim atrybucie, albo jeżeli to wiem, jakie metody ma i jakie parametry one przyjmują.
CTRL + SPACJA - lista metod
CTRL + Q - dokumentacja jak jest potrzebna
CTRL + P - lista parametrów z podświetleniem który akurat wpisuje (czasami się przydaje)
Proste prawda ? :-)

Co do komentarza do @markac to może i ja odpowiem. Jeżeli np przekazujemy w GET id jakiegoś elementu to wolę żeby w URL on został. Mogę go odebrać przy okazji obsłużenia formularza i np później użytkownika gdzieś przekierować. Poza tym kod nie zyskuje na czytelności z prostego względu. Raz parametr masz w URL a raz ukryty w formularzu. Po co ? Lepiej trzymać go w URL i nie ruszać.
GET i 256 znaków to chyba jakieś prehistoryczne czasy. Z tego co pamiętam, najmniej znaków może łyknąć IE (6 na 100%, nie pamiętam jak starsze) i jest to 2083 znaki chyba. Konkurencja radzi sobie nawet z 2x dłuższymi ciągami znaków.

@markac: i nie napisałem, że pytania są głupie, więc nie wciskaj mi tego w usta ;) Napisałem, że widząc takie pytania, można się załamać, ponieważ dotyczą rzeczy wielokrotnie elementarnych i będących do sprawdzenia samemu w kilka minut. To nie jest więc kwestia wyśmiewania głupoty, ale uderzania głową w mur na widok, wspomnianego także przez Dariusza, lenistwa. Bo prościej iść na forum i walnąć temat jakich było już wiele i dziennie pojawia się przynajmniej raz, niż użyć wyszukiwarki nawet w obrębie forum, która mu pokaże, że takich lub podobnych było już kilkaset przynajmniej ;) Nieraz wystarczy chwilka lektury dokumentacji właśnie i człowiek wie wszystko czego potrzebuje. Tymczasem ludzie nie czytają, a potem się użalają jaki ten język trudny lub nielogiczny. Tymczasem większość ich problemów by nie istniała, gdyby tylko byli łaskawi czasem poczytać kilka stron. Nie musza znać na pamięć tego. Wystarczy, że będa wiedzieć gdzie tego szukać w przyszłości. Po tym wlasnie poznasz programiste od klepacza. Pierwszy ciągle poszerza swą bazę wiedzy, nawet o nietypowe rzeczy. Przykład? Ja właśnie czytam książkę Stallingsa o metodach zapewnienia bezpieczeństwa w sieci. Nie tylko jakie są metody choćby szyfrowania danych, ale cały mechanizm i historia począwszy od kodu Cezara na md5, sha1 czy pgp skończywszy. Nawet liźnięto tam jak działała niemiecka Enigma ;)

Rozwinięcie phpDoc-a to dobry pomysł. Ludziom powinno się przydać gdy zobaczą jakieś proste przykłady i zrozumieją zarysowaną w obecnym artykule ideę.

Tak. Tamten artykuł był dobry, ale pewne rzeczy z niego umknęły, a które choćby teraz wspomniałem, jak choćby bindowanie parametrów w PDO. Właściwie to o samym PDO mozna by więcej napisać. To w sumie standard niemal wszędzie w aplikacjach, ale wiele osób używa mysql_*. Sam tak robię w części aplikacji nieobiektowych, ale wiem jak się zabezpieczać (filter_var, ctype, regexpy filtrujące itd. ).

Co do edytorów to może faktycznie za bardzo hurraoptymistycznie podszedłem. Raczej nie zmieściłbyś tego w limicie... nawet kilka razy większym ;)

Codo produkcji masz rację. Wygoda i szybkość przede wszystkim.

Co do formularza tu także masz rację, ale jak wspomniałem, zależy wiele od przeznaczenia formularza i tego jakie operacje przed, w, po, nim przeprowadzamy. W większości przypadków przekazywanie parametrów osobno przez GET w postaci zmodyfikowanego action, a część w POST, jest zwyczajnie później przełożone na nieco większą ilość kodu. Bo to czy dostaniemy GET czy POST jako parametr to żadna różnica tak naprawdę.

Co do GET to nowsze przeglądarki łykają 64kB, ale potem mogą pojawiać się problemy. Inna sprawa czy serwer taki url obsłuży, bo nie jest to regułą. Zależnie od konfiguracji może puścić, albo sypnąć błędem. Error 413 i 414 z powietrza się nie biorą ;)

Będąc złośliwy przytoczę cytat z bash.org:
wiesz jaki jest najkrótszy żart informatyczny?
?
programista php

@qweer, będąc złośliwym, przytoczę cytat mój własny:
wiesz jaki jest najkrótszy żart informatyczny ?
uwaga troll

A na poważnie to obawiam się że w dobie internetu, to programiści takich języków jak PHP, Ruby czy Python mają najwięcej do powiedzenia. A wraz z rozwojem Javascript, szybszych przeglądarek i takich technologii jak Canvas, WebGL i całej masy elementów HTML5 możemy tworzyć aplikacje pozbawione wszystkich wad aplikacji desktopowych.

Chyba że przez "programista php" miałeś na myśli klepacza stronek w HTML za 300zł. Cóż, to jak żartowanie z Lamborghini bo widziało się Malucha :P

Moja rada - zostań w tym przekonaniu. Nie będę tłumaczył dlaczego :-)

@qweer: nie będąc złośliwy... Zanim poznałem PHP pracowałem z: C/C++, Turbo Pascal, Delphi, Java, żeby wymienić te najbardziej znane. Dla mnie PHP, JS i cała ta otoczka to po prostu kolejne języki w dorobku programistycznym. Co będzie następne? Sam nie wiem... Coś jeszcze do dodania masz zanim zaczniesz kolejne złośliwości? Co do żartu zaś samego, to nie jest za grosz śmieszny, a jego autorem ewidentnie jest osoba mająca niskie ego i chcąca się podbudować tym, że zna C lub Javę :) Ja też i co z tego? Znam także nieco ASM i jakoś nie jest to powodem do wywyższania się nad innymi. Kwestia kultury i charakteru.

A by odbić piłeczkę... Wiesz jaki jest jeszcze krótszy? Htmlowiec. Bo przykro mi, ale ktoś kto składa jedynie znaczniki, z programowaniem nic nie ma wspólnego. A tacy też siebie nazywają programistami. Nie myl tego z frontdeveloperem, bo on przynajmniej JS musi umieć, a w nim już programowanie jest.

Zwłaszcza w OOP a szczególnie w 90% przypadków, kiedy jest niepotrzebnie angażowany trzeba dbac o dokumentację. gdyz taka metoda programowania nie jest deskryptywna i jest zagmatwana. Trzeba sie ratować dokumentacją, chociaz to niewiele ułatwia.

@BaXx, to Ty chyba preferujesz "inne" OOP niż ja. OOP stosujemy właśnie po to by życie sobie ułatwiać.
Dziedziczenie, hermetyzacja czy polimorfizm daje szerokie pole do popisu.
No ale z OOP jak z młotkiem. Jest nieoceniony kiedy chcesz przybić gwoździa ale jak nie umiesz się nim posługiwać to tylko poobijasz sobie palce.
O samą dokumentację trzeba dbać zawsze i wszędzie.

Autor to niech najpierw napisze artykuł o niemieszaniu polskich i angielskich nazw a potem zajmuje sie phpdocem

Używanie polskich lub angielskich nazw to tylko konwencja programistyczna i jej używanie jest opcjonalne, tak samo zresztą jak stosowanie phpDoca. Stosowanie zresztą tej konwencji tyczy się zresztą głównie nazw klas, funkcji i zmiennych. Dla potrzeb ogólnych zapewne autor pisze po angielsku, ale na potrzeby poradnika tutaj - użył polskiego by nie musieć dublować się z opisem co jest czym i co robi lub do czego służy. tak więc jeśli chcesz juz coś wytykać, to niech to będzie konstruktywna krytyka, a nie czepianie się czegoś co de facto uchybieniem nie jest, ale ma służyć lepszej czytelności dla odbiorców artykułu.