Le 10 idee sbagliate su PHP – Parte 6/10

An article by duplikey    No Comments

Questo articolo è stato pubblicato 8 mesi 6 giorni giorni fa quindi alcuni contenuti o informazioni presenti in esso potrebbero non essere più validi. Questo sito non è responsabile per eventuali errori causati da questo problema.

Eccoci con il sesto appuntamento sui falsi miti di PHP. Per chi non avesse letto i precedenti post (che sono linkati alla fine dell’articolo) lascio sempre il link all’articolo originale in inglese. Oggi si parla di documentazione.

6. La documentazione di PHP è scadente o insufficiente

Questa è probabilmente la peggiore lamentela che abbia mai sentito, ma penso sia necessario citarla perché l’ho sentita ripetere più di una volta. In realtà ho sentito persino qualcuno dire che la documentazione di PHP è talmente scadente che sono necessari i commenti per migliorarla.

Se c’è una sola cosa buona in PHP, questa è di certo la documentazione. La documentazione è ben strutturata, chiara e, dato il tempo necessario al team della documentazione, molto completa. I commenti degli utenti, che sono presenti nella pagine della documentazione, la arricchiscono e la rendono più completa.

Non ho ancora visto nessun progetto software, open source o meno, che ha una documentazione migliore di PHP. Il fatto che includa i commenti degli utenti, rende la documentazione di PHP una Documentazione 2.0 – Documentazione arricchita dagli utenti.

Il team  documentazione di PHP fa un fantastico lavoro. Non solo si occupano della documentazione principale in Inglese, ma hanno anche dei team dedicati che si occupano di tradurla in decine di lingue diverse. Questo è sicuramente uno dei motivi per cui PHP è così popolare nel mondo. Onore a tutti quelli che aiutano nella documentazione di PHP.

Il team  documentazione di PHP non può fare miracoli. Gli aspetti che PHP copre sono così estesi che è impossibile conoscere ogni dettaglio oscuro che fa funzionare PHP in maniera diversa da come ci si aspetta, su alcune piattaforme. Ci possono essere bug in PHP che possono causare comportamenti sbagliati, ma questo non è di certo un errore del team  documentazione.

Ecco perché i commenti degli utenti sono così importanti. Forniscono delle informazioni addizionali che permettono agli utenti PHP di conoscere i comportamenti inattesi che il team documentazione non riesce ad anticipare.

Inoltre, spesso potete trovare, tra i commenti alla documentazione, codice di esempio per eseguire certi task che gli utenti PHP si aspettano da una determinata funzione. Questo rende la documentazione di PHP con i commenti degli utenti ancora più ricca di quanto non possa essere senza commenti. Non è fantastico?