Come usare PHPdoc in Eclipse

Siamo attualmente all'inizio di un nuovo progetto e vorremmo (per una volta) commentare il più ansible fin dall'inizio per aiutare lo sviluppo futuro.

Ho cercato di scoprire quali sono le migliori pratiche di phpDoc in Eclipse, ma con risultati piuttosto sottili.

Puoi condividere le tue migliori pratiche e trucchi per usare phpDoc per commentare cose in Eclipse?

Non esiste un "vero standard" su ciò che dovrebbe essere commentato e come, ma alcuni tag sono usati praticamente da tutti coloro che commentano il suo codice.

Ad esempio, generalmente uso alless:

  • una breve descrizione
  • opzionalmente, una lunga descrizione
  • @param type name description : per i parametri di funzioni / methods
  • @returns type : per il valore di return di funzioni / methods
  • @throws ExceptionType : se le funzioni / methods @throws ExceptionType in alcune circostanze
  • @see .. : quando voglio fare riferimento a un altro file o a un URL che fornisce ulteriori informazioni
  • a seconda della struttura del progetto, posso anche usare @package e @subpackage
  • Un altro che è bello quando si hanno properties; magiche in una class (non possono essere visti dal proprio IDE, come sono scritti nel codice) è @property type $name : consente a Eclipse PDT di eseguire il completamento automatico, anche sulle properties; magiche – Doctrine usa questo, per esempio.

Molti di questi sono usati da Eclipse PDT per aiutarti durante la codifica (in particolare @param ) ; ma sentitevi liberi di aggiungere alcuni che non sono usati da Eclipse PDT: se generate la documentazione dal vostro codice, può sempre essere utile 😉

Il miglior consiglio che posso darti è di dare un'occhiata al codice sorgente di alcune grandi applicazioni e / o framework (Zend Framework, Doctrine, …) , per vedere come viene commentato il loro codice – è probabile che siano usando qualcosa che è ben accettato.

Ad esempio, se dai un'occhiata al codice Zend Framework, puoi trovare cose come questa per una class:

 /** * @package Zend_Cache * @subpackage Zend_Cache_Backend * @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com) * @license http://framework.zend.com/license/new-bsd New BSD License */ class Zend_Cache_Backend_Apc extends Zend_Cache_Backend implements Zend_Cache_Backend_ExtendedInterface 

E così per un metodo:

 /** * Test if a cache is available for the given id and (if yes) return it (false else) * * WARNING $doNotTestCacheValidity=true is unsupported by the Apc backend * * @param string $id cache id * @param boolean $doNotTestCacheValidity if set to true, the cache validity won't be tested * @return string cached datas (or false) */ public function load($id, $doNotTestCacheValidity = false) 

Ad each modo, la cosa più importnte è essere coerenti: each membro della tua squadra dovrebbe commentare nello stesso modo, seguire le stesse convenzioni.

Come minimo, vorrei alless attenermi a quali tag minimi di phpdoc vengono automaticamente inseriti da Eclipse in base al codice.

Il secondo livello minimo per cui mi aspetterei sarebbe mantenere felice PhpDocumentor. Dopo aver eseguito PhpDocumentor contro il tuo codice, cerca la pagina errors.html nella root dei tuoi documenti. Questo elencherà qualsiasi cosa non piaccia a PhpDocumentor, come ad esempio non avere docblocks a livello di file. Potresti cercare di riportre l'elenco degli errori a zero.

Il terzo livello che potresti raggiungere è quello di soddisfare uno degli standard di codifica inclusi nell'applicazione PHP_CodeSniffer su PEAR [1]. Uno svantaggio è che questi standard si concentrano in modo specifico sul codice stesso, ma tutti gli standard includono le regole relative alla documentazione del codice.

[1] – http://pear.php.net/package/PHP_CodeSniffer