web-dev-qa-db-ja.com

関数とクラスメッドのインラインキューイングで、@ seeタグを使用するタイミング

「内部で大きく依存している関数、メソッド、またはクラスへの参照」と書かれています。 at https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#1-functions-class-methods .

OK。しかし、私が関数を持っているなら、それはいつも何かがそれを使っていることを意味します。使わないのであれば関数を書く必要はないからです。そして、「大きく依存している」とはどういう意味ですか?それは私が関数を削除しようとした場合、従属関数は正しく機能しないことを意味しますか?それでもすべての関数、そしてそれでも私は常に "@ see"タグを使うべきです。

WPやWCのコードを見ると、 "@ see"タグがどういうわけかランダムに使われています。

私は本当に手に入れません。説明してください。 "@see"タグはいつ使用すべきですか?

1
vladlu

"@ see"タグがどういうわけかランダムに使われている

結局のところ、どんな文書化も文書化する価値があるのか​​、そしてどのようにするのかについてのプログラマーの決定に依存するので、不思議ではありません。

一般的なドキュメンテーションは、コードが極端に自明でない場合を除き、コードの口頭での説明ではありませんが、コードの機能とその理由についてのわかりやすい要約を追加してください。そのため、コード内で使用されている関数は既にコード内にあるため、@seeで参照するにはふさわしくありません。何らかの形式で入力を取得したり、出力を処理しようとしているために、異なる関数の動作に依存する場合は、この関数を使用してください。ここでは、入力と出力の定義が非常に緩やかです。

ですから、それは判断の呼びかけにかかっています。あなたは、関数Bについて何も知らずに関数Aがなぜするのか理解することができますか?そうであれば、@seeは必要ありませんが、例えばAがBによって使用されるグローバル変数を設定する場合、おそらく両方が互いへの参照を含むべきです(明らかに良いコードはそのようなものを持ってはいけません;))。

0
Mark Kaplun