厳密な型指定を使用する場合、docblock typehintsは冗長です

私はかなり大きなプライベートコードベースを持っていますが、これは約10年にわたって進化しています。私はphpDocumentorを使用していませんが、オープンブロックプロジェクトではdocblockセクションを使用することが標準になっているため、リポジトリ内のすべてのパブリックメソッドにもdocblockを記述することを採用しました。ほとんどのブロックには、すべてのパラメーターと戻り値の型に関する小さな説明と型ヒントが含まれています。

静的解析の登場により、これらのタイプヒントは矛盾やバグの発見に大いに役立ちました。最近、PHPのtypehintsを使用して、可能な場合はすべてのパラメーターと戻り値の型ヒントを含むように、コードベース全体（PHP7.2で実行中）を変換しました。そして今、私は疑問に思っています...これらのdocblock typehintsは冗長ではありませんか？すべてのdocblockを絶えず変化するコードと同期させ、新しい情報を追加しないため、それらを完全に削除する方が良いのではないかと思っています。

一方で、ドキュメントを削除することは、それが冗長であっても気分が悪くなります。もう1つは、既にタイプヒントが付けられている日常的なタイプヒントの繰り返し禁止の原則を破りたいという気持ちです。

コードで見つけることができる情報は、コメントで複製しないでください。

せいぜい、それらの同期を維持するための無駄な努力です。より可能性が高いのは、最終的に同期が外れることです。その時点で、彼らはただ混乱しています。

静的に型付けされた言語（Java、C＃など）で同等のDocBlockを見ると、docコメントに型情報が含まれていないことがわかります。これがあなたのPHPコードに当てはまる限り、私はこれに従うことを強くお勧めします。もちろん、タイプヒンティングを適用できない場合でも、コメントが最善の選択肢です。

これはPHPには関係ありませんが、型が暗黙的に推論されている場合（Haskellなど）、型情報の重複は意味をなします。

はい、docblockはphp 7で冗長になりました。

コーディングのほとんどの時間は読書に費やされるため、同じものを2回読む必要がある場合、生産性に影響します。さらに、実際に重要なコメントを見逃しやすくします。

特定のタイプの配列（@return int[]または@param SomeStatus[] $statusList）のヒントを入力したい場合、またはメソッド、パラメーター、戻り値に関するコメントを追加したい場合を除き、docblockはもう作成しません。docblockがある場合、すべてのパラメーターと戻り値の型がdocblockにないときにトリガーするphpstormインスペクションを無効にすることが重要であることがわかりました。

通常、コードとドキュメントの対象読者は異なります。ドキュメントはその機能のユーザー向けです。型を理解するためにコードを見る必要はありません。したがって、ドキュメントには、タイプを含むすべての必要な情報を含める必要があります。

一部のシステムでは、コードからタイプを取得できるため、ドキュメントでパラメータータイプを指定する必要はありません。PHPDocはそのようなシステムではありません。代わりに、@paramタグは文書化されています

提供される場合、期待されるものを示すためにタイプを含まなければならない

PHPDocがドキュメントタイプのヒントをコードタイプのヒントと照合するため、「すべてのdocblockを常に変化するコードと同期させるためのかなりの作業」が多少削減されます。これは一種のリンティング/静的分析なので、ドキュメント生成を自動テストパイプラインの一部にします。

あなたが自問したいかもしれないもう一つの質問は、これらの機能が「常に変化している」とき、なぜこの詳細に文書化されているのかということです。通常の動機は、インターフェイスのHTMLリファレンスマニュアルを作成することです。しかし、ドキュメントがIDEの外で決して読まれない場合、またはドキュメントが理にかなっている安定したインターフェイスがない場合、詳細なdocblockは不要であり、誤解を招く可能性さえあります。概要のみを記述し、安定した設計に到達するまで完全なドキュメントを延期する方が良い場合があります。