В настоящее время мы находимся в начале нового проекта и хотели бы (на этот раз) комментировать как можно больше с самого начала, чтобы помочь в будущем развитии.
Я попытался выяснить, какие лучшие методы использования phpDoc в Eclipse, но с довольно тонкими результатами.
Можете ли вы поделиться своими рекомендациями и трюками с использованием phpDoc для комментариев в Eclipse?
Не существует «реального стандарта» о том, что следует комментировать и как, но некоторые теги используются почти всем, кто комментирует его код.
Например, я обычно использую как минимум:
@param type name description : для параметров функций / методов @returns type : для возвращаемого значения функций / методов @throws ExceptionType : если функции / методы выбрасывают исключение при некоторых обстоятельствах @see .. : когда я хочу сделать ссылку на другой файл или URL, который дает больше информации @package и @subpackage @property type $name : он позволяет Eclipse PDT делать автоматическое завершение, даже при магических свойствах – Доктрина использует это, например. Большинство из них используются Eclipse PDT, чтобы помочь вам при кодировании (особенно @param ) ; но не стесняйтесь добавлять некоторые, которые не используются Eclipse PDT: если вы создаете документацию из своего кода, она всегда может быть полезна 😉
Лучшим советом, который я могу вам дать, было бы взглянуть на исходный код некоторых крупных приложений и / или фреймворков (Zend Framework, Doctrine, …) , чтобы увидеть, как их код прокомментирован – скорее всего, они используя что-то, что хорошо принято.
Например, если вы посмотрите на код Zend Framework, вы можете найти такие вещи для класса:
/** * @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
И как это для метода:
/** * 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)
Во всяком случае, самое главное – быть последовательным: каждый член вашей команды должен прокомментировать тот же путь, следовать тем же соглашениям.
По крайней мере, я бы по крайней мере придерживался того, какие минимальные теги phpdoc автоматически вставляются Eclipse на основе вашего кода.
Второй минимальный уровень, к которому я стремился, – это держать PhpDocumentor сам счастливым. Когда вы запустите PhpDocumentor против своего кода, найдите страницу errors.html в корне ваших документов. Это будет перечислять все, что не нравится PhpDocumentor, например, не иметь докблоков на уровне файлов. Вы можете стремиться довести этот список ошибок до нуля.
Третий уровень, на который вы могли бы стремиться достичь, будет удовлетворять любому из стандартов кодирования, включенным в приложение PHP_CodeSniffer в PEAR [1]. Недостатком здесь является то, что эти стандарты более конкретно фокусируются на самом коде, но все стандарты включают в себя правила, касающиеся документации по коду.