3

私たちは現在、新しいプロジェクトを開始しており、将来の開発を支援するために、最初から可能な限りコメントしたいと思います.

私は、Eclipse で phpDoc を使用する際のベスト プラクティスを見つけようとしましたが、結果はごくわずかでした。

Eclipse で phpDoc を使用してコメントする際のベスト プラクティスとコツを教えてください。

4

2 に答える 2

10

コメントする内容と方法についての「実際の標準」はありませんが、一部のタグは、自分のコードにコメントするほとんどの人が使用します。

たとえば、私は一般的に少なくとも以下を使用します：

  • 簡単な説明
  • オプションで、長い説明
  • @param type name description：関数/メソッドのパラメータ用
  • @returns type：関数/メソッドの戻り値
  • @throws ExceptionType：関数/メソッドが特定の状況で例外をスローした場合
  • @see ..。：別のファイル、またはより多くの情報を提供するURLのいずれかを参照したい場合
  • プロジェクトの構造によっては@package、@subpackage
  • クラスに魔法のプロパティがある場合に便利なもう1つの方法（コードで記述されているため、IDEでは表示できません）：@property type $name魔法のプロパティでもEclipsePDTがオートコンプリートを実行できるようにします-Doctrineはこれを使用します、 例えば。

それらのほとんどは、コーディング時に役立つように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)


とにかく、最も重要なことは一貫性を保つことです。チームのすべてのメンバーが同じようにコメントし、同じ規則に従う必要があります。

于 2010-02-21T14:11:38.453 に答える
2

最低限、コードに基づいてEclipseによって自動的に挿入される最小限のphpdocタグに固執します。

私が目指している 2 番目の最小レベルは、PhpDocumentor 自体を満足させることです。コードに対して PhpDocumentor を実行したら、ドキュメントのルートにある errors.html ページを探します。これにより、ファイルレベルの docblock がないなど、PhpDocumentor が気に入らないものがすべてリストされます。そのエラーのリストをゼロにするよう努めることができます。

達成を目指すことができる 3 番目のレベルは、PEAR の PHP_CodeSniffer アプリケーションに含まれているコーディング標準のいずれかを満たすことです [1]。ここでの欠点は、これらの標準がより具体的にコード自体に焦点を当てていることですが、すべての標準にはコードのドキュメントに関する規則が含まれています。

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

于 2010-02-26T00:27:18.320 に答える