[Gruppo-web] Documentazione codice tema

[Riccardo Padovani]

On Fri, Jun 13, 2014 at 12:06:49PM +0200, Mattia Migliorini wrote:
> Ciao a tutti,
> separo il thread altrimenti è un casino. Parliamo di documentazione.
> 
> == Perché è importante documentare bene il codice

E vabbé, qua credono lo sappiano tutti :-P

> == 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.

Ottimo, essere forzati ad avere uno stile comune è molto utile.
Dando una veloce occhiata al sito poi non sembra niente di trascendentale, non
credo ci voglia molto a usare le loro linee guida
 
> 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.

Ottimo anche questo, poi vediamo di automatizzare la procedura

> == 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 per me!

Ciao,
-- 
Riccardo Padovani
www.rpadovani.com