PHPDocの冗長性は価値があるよりも厄介ですか？ [閉まっている]

Question

今日初めてPHPDocを使用しようとしましたが、すぐに問題に遭遇しました。

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

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

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

それはまた、ワークフローにねじれを投げます。抜本的な変更を加える必要があるまで、すべてがうまくいきます。よく文書化されたドキュメントブロックを使用すると、突然コードをリファクタリングする必要がなくなりますが、これらの退屈な詳細をすべて書き直す必要があります。あなたが言う最後まで待って？ハァッ！そうなると、ドキュメントは決して作成されません。

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

長い話-私はPHPDocが好きで、よく文書化されたコードが大好きです-しかし、コード1行ごとに5行のコメントは非常に多すぎます！。欠けている機能はありますか？これは一般的な問題ですか？

Answer 1

それが過剰であるかどうかは、アプリケーションの使用目的に大きく依存します。単一の企業またはグループのみが使用するアプリを作成している場合、すべての単一変数の詳細なドキュメントは必要ないでしょう。

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

他の開発者や企業に配布するつもりのアプリを書いていて、自分のアプリを他のシステムと統合したり、その機能を拡張したりすることを期待した場合、PHPDocのより広範な使用をより重視します。この種の詳細は、長期メンテナンスの際に間違いなく役立ちます。

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