[Gruppo-web] Documentazione codice tema

[Mattia Migliorini]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Ciao a tutti,
separo il thread altrimenti è un casino. Parliamo di documentazione.

== Perché è importante documentare bene il codice

Per qualche semplice motivo:
- - Vogliamo rendere il progetto pubblico, quindi altri devono poterci
mettere le mani facilmente;
- - Dobbiamo poterci mettere le mani noi stessi tra 1 mese, 6 mesi, 1
anno...

Come potete vedere, abbiamo già cominciato a commentare prolissamente
il codice.

== Linee guida

Ieri sera ho proposto di sfruttare PhpDocumentor [1], un progettino
interessante che vi illustrerò tra pochissimo.
Questo richiede di seguire delle regole nella scrittura della
documentazione. Potete trovare tutto nel sito ufficiale del progetto.
Sappiate che queste regole non sono una rottura di scatole, ma aiutano
molto, perché la documentazione che ne risulta è molto pulita e
comprensibile.

PhpDoc offre un phar che legge tutti i file che gli diamo in pasto e
genera automaticamente una documentazione basata sui commenti nel
codice. Il risultato è un indice di tutte le classi, tutte le
funzioni, tutte le costanti che vengono utilizzate. Un buon indice,
utile per andare a controllare quali parametri richiede una funzione
che stiamo usando, per esempio.

== La proposta

Quello che propongo di fare come prima cosa è guardarsi il sito del
progetto [1]. In secondo luogo, discutere sull'adozione o meno di
questo pratico strumento.

[1] http://www.phpdoc.org/
- -- 
Mattia Migliorini

Web Designer
Website: www.deshack.net
OpenPGP key: AA3B90BC
Fingerprint: 5F30 BEB3 224E A831 1DCE  F554 7E64 2AFF AA3B 90BC
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Icedove - http://www.enigmail.net/

iQIcBAEBAgAGBQJTms05AAoJEH5kKv+qO5C8ZMsP/RS9CIAq4USv0zh3YF9UahLe
V6//ZpUN4aFV6ZIu/j1Tvx2bIRPND3UzjmfluSRLgE57t1jxjH2YthA5N5fH9YrY
FOPVEXcv5JGRrr7YHKK3sqNweQGYDnnG8pcYSSPAcFiO/Gxga23wWnQMBSQlvUHv
GLwFhXoxO1nGxDl6PdH4Ne8HrZdUAt6R0Dd6D7lR8W8kUIDnu+DPxDStcObpYcTF
Pc5R1DtkImi4KlS8I78OSi+lNiAy3FP2HNVkiX4DUyk+z9MJwi8eI1epCxxFJV9E
971MefGGBR7kENr/N3lggedGeXP75eKkdqcAxwDAAj75wGOMkQdy+HzN4y31KmD1
10UTN25a7cmrhqWtkoKjJi8Vv+7mHM1h5KBzcOdZuLeei7ovDFf6G7N8hxHrxJDU
p4bXMF4UPhkRB8IWAhh9XtqLZ7Lw4st4pl+v4R5SPxaODQOOFupFrzxy5+Ea33Hl
r3I8Yp3qnzUqU0pprfRMSJpjg/R5TUh+57C91VhOY3hlp/S0hwq2zpJudEfj/ZTz
96Gtkfx8u5CmahU2wfYqTQ39eBn/EH+il3fJNOXBJe0gFRo3AnS6vNproaEbj/Y/
lWmRKl79G6DCTehbkObX3J+aJSgRyMZnGc52u6MDlpZ/L4CH17z7Zm1bTdaDdzm5
27i27/2gJZ/SsEiWongo
=lSXV
-----END PGP SIGNATURE-----
-------------- parte successiva --------------
Un allegato non testuale è stato rimosso....
Nome:        deshack.vcf
Tipo:        text/x-vcard
Dimensione:  227 bytes
Descrizione: non disponibile
URL:         <http://liste.ubuntu-it.org/cgi-bin/mailman/private/gruppo-web/attachments/20140613/694cdc05/attachment.vcf>