4

今日初めて PHPDoc を使用してみましたが、すぐに問題が発生しました。

変数宣言の 1 行ごとに、少なくとも 5 行のコメントがありました。例：

/**
 * Holds path the remote server
 * @name ...
 * @global ...
 */
 $myvar = ...

もちろん、見返りは素晴らしいですが、これにより、10 行の構成ファイルが 60 行のファイルに変わります。記入するのに永遠に時間がかかりますが、単純なワンライナーよりもはるかに多くのことを追加できるとはまだ確信していません.

また、ワークフローにねじれが発生します。大幅な変更が必要になるまでは、すべて問題ありません。ドキュメント ブロックが十分に文書化されているため、突如としてコードをリファクタリングする必要がなくなりましたが、これらの面倒な詳細をすべて書き直す必要があります。あなたが言う最後まで待って？ハッ！その後、文書化は決して起こりません。

その上、コードの途中で C スタイルの /**/ コメントを強制されます。これにより、必要に応じて大きなブロックをコメントアウトする機能が失われるため、開発中に私は夢中になります。コードの大きなブロックをコメントアウトするには、 :range,s/^/#/ のようなものをプルする必要があります。後で元に戻します。迷惑！

簡単に言えば、私はPHPDocが好きで、よく文書化されたコードが大好きですが、コードの1行ごとに5行のコメントは多すぎます! . 不足している機能はありますか? これはよくある問題ですか？

4

1 に答える 1

6

やり過ぎかどうかは、アプリケーションの使用目的に大きく依存します。1 つの企業またはグループのみが使用するアプリを作成している場合は、すべての変数の完全なドキュメントはおそらく必要ありません。

たとえば、私は現在、かなり広範なコード ベースのプロジェクトに取り組んでいますが、開発者はほとんどいません (今のところ、私だけです)。クラスとメソッドの 2 つの目的で PHPDoc ブロックを追加しています。それ以外については、頻繁にコメントしますが、冗長な PHPDoc 形式ではありません。このコードのほとんどは 3 人か 4 人しか見ることができず、彼らが必要とする情報はブラック ボックスの情報です。つまり、このメソッドに何を送信し、何を取得する必要があるかということです。彼らは、プライベート クラス変数の目的ではなく、モデルからデータを取得する方法を知りたいと考えています。

他の開発者や企業に配布することを意図したアプリを書いていて、彼らが自分のアプリを他のシステムと統合したり、その機能を拡張したりすることを期待していた場合、PHPDoc をより広範囲に使用することに価値を置きます。そのような詳細は、長期的なメンテナンス中に間違いなく役立つ可能性があります.

適切な例として、私の現在のプロジェクトでは、ある時点で、他のサイトからアクセスできるように API を作成する必要があります。API には、コード行よりも多くのコメントとドキュメントが含まれていることは間違いありません。

于 2009-04-30T02:37:39.853 に答える