ファイル、クラス、コンストラクターを文書化する適切な方法は何ですか？
コンストラクターとクラス、および単一のクラスのみを含むファイルのコメントブロックを一貫して書き込むための、最も有用/最も標準的/最も驚くべき方法は何ですか？
- コンストラクターではなく、クラスのコメントブロック
- クラスではなくコンストラクターのコメントブロック
- コンストラクターとクラスの両方のコメントブロック->その場合、それぞれにどのような詳細を入れる必要がありますか？
そして、ファイル自体？クラスが1つしかない場合、コメントブロックが必要ですか？どのような詳細がそこに行くべきですか？
クラス、コンストラクター、ファイルコメントブロック間の繰り返しをできるだけ避けたいと思います。
これは、あなたの状況と、一緒に働く人々またはあなたの後に来る人々の想定されるスキルレベルに大きく依存します。
フレームワーク、ライブラリ、またはユーザーがすべてのスキルレベルであると通常想定している種類のものを公開する場合、mightできるだけ多くの些細ながらくたを文書化する必要がありますコミュニティが処理しなければならない質問の負荷を減らすため。
ドキュメントが大きな苦痛になる可能性があると思う例から始めましょう。
何が絶対に必要ですか
PHPDocを使用する場合は、ファイルdocブロックとその後の別のdocブロック（通常はクラスdocブロック）が必要です。
それらには@packageタグが**必要*です。それ以外はすべてオプションです。
これまでのところ、@packageタグでさえ、プロジェクト用に自動的に生成できる可能性があるため、オプションであると言います。そして、私が正しく覚えていれば、PHPDocを使用すると、タグのないすべてのものにデフォルトのパッケージを設定することもできます。
一般的なドキュメントについては、例から始めましょう（より長い例は最後にあります）：
「uri」の意味を何回説明できますか。
getUriの場合、URIが何を表すかが説明されていることに注意してください（私が想定するコメントで何か話したいことがあるだけです）が、isAbsUriにはないので、少なくとも「absは絶対を意味する」と2回言います。
オープンソースプロジェクトでない場合（またはCOMPLETE !!! 11elevenapiドキュメントを出荷する必要がある場合）：
stronglyドキュメントの代わりに適切で長く説明的なクラス、変数、メソッド名を使用することをお勧めします。
Docブロックに何かを再度書き込むことによるメリットはありません。また、2011年であり、120文字幅の端末とオートコンプリートがあるため、一部の文字を節約するためにすべてを短縮する必要はありません。
些細なことを文書化することはあなたとあなたのチームを傷つけるとさえ主張します誰もあなたから価値を得られないことに時間を無駄にすることによって、常に些細なドキュメントを書く習慣になりますもう読んでいません。
良いコメントは何かが行われた理由を説明する必要がありますが、コード自体はそれ以上のコメントを必要とせずにどのように説明する必要があります。
冗長ドキュメントの私のお気に入りの例は次のとおりです。
class myClass {
/**
* Constructor
*/
public function __construct() {
}
いくつかのガイドラインでは、[〜＃〜] have [〜＃〜]to document[〜＃〜]すべて[〜＃〜 ]そしてあなたは人々が何度も何度も明白なことを述べることになります。
これは価値を追加しませんが、コードを読むときに時間を浪費します。
固有名詞の例：
class Person {
/**
* Set a persons weight in Kilogram
*
* @param float $kg Weight in Kilogram
*/
public function setWeight($kg) {}
一部の人は別のシステムを使用している可能性があり、「kg」をグーグルで検索できないため、「kg」の意味を説明する必要があるため、このコードは簡単に文書化できます。
私は書くことに賛成です
class Person {
/**
* @param float $kilogram
*/
public function setWeight($kilogram) {}
setWeightでPersonを呼び出すと、人に重みを設定することが本当に期待できるため、docブロックは不要です。もう一度書き出す必要はありません。
$ kilogrammをパラメーターとして使用すると、ドキュメントで説明する手間も省けます。環境によっては、測定単位が本当にわからない場合は、誰もが「キログラム」をグーグルで検索することが期待できます。
@PHPDocドキュメント
- もちろん私の謙虚な意見はすべて
- タイプヒントを使用しない場合は、常に@paramタグを使用してください。
- 常に@returnタグを使用してください
- @authorタグはまったく使用しないでください。 コレクションコードの所有権の方が価値があります そして情報はとにかくソース管理リポジトリにあります。
- 必要な場合にのみ@copyrightタグを使用してください。私はライセンスファイルを持っているだけが好きですが、私は弁護士ではないので、それが必要かもしれません。
インラインコメント：
public function generateReport() {
// get the db connection
$reg = WhateverGlobalStorage::get(“db“);
// auth
if(!$reg->getOne("SELECT view_report FROM USER ...")) {}
// template
$id = $reg->getOne("select ... ");
// render
new ReportTemplate($id); // ...
}
それらが別々の「ブロック」である場合は、それらを記述的な名前付き関数に移動するだけです。
public function generateReport() {
$this->checkAuthentication();
$template = this->createReportTemplate();
$this->renderReport($template);
}
// Not perfect but at least you can grasp what the method does much quicker
追加リソース：
いくつかの会議でこのテーマについて行ったプレゼンテーションのスライド： Slideshare: clean-code-stop-wasting-my-time
そして、追加の小さく、少し古い、暴言： they-told-you-to-document-everything-they-lied
本の参照：
Clean Code: A Handbook of Agile Software Craftsmanship
より長い例
abstract class xyzRequest {
/**
* Initializes this xyzRequest.
*
* Available options:
*
* * logging: Whether to enable logging or not (false by default)
*
* @param xyzEventDispatcher $dispatcher An xyzEventDispatcher instance
* @param array $parameters An associative array of initialization parameters
* @param array $attributes An associative array of initialization attributes
* @param array $options An associative array of options
*
* @return bool true, if initialization completes successfully, otherwise false
*
* @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest
*/
public function initialize(xyzEventDispatcher $dispatcher, $parameters = array(), $attributes = array(), $options = array()) {
そのドキュメントの内容を1行ずつ見ていきましょう。（ここで少し冗談を言って、私の主張を理解します）
* Initializes this xyzRequest.
それで、xyzRequestで-> initializeを呼び出すと、そのリクエストが初期化されますか？本当に？ Okそれなら、あなたがそう言うなら！
* Available options:
*
* * logging: Whether to enable logging or not (false by default)
2番目または3番目のパラメーターではなく、3番目のパラメーターのオプションが通知されますが、フレームワークを知っていれば、それらを知っているでしょうか。 （誰かが使用を言わずに->初期化が何をするのか理解できないので、私たちはそれほど賢くないかもしれません...）
* @param xyzEventDispatcher $dispatcher An xyzEventDispatcher instance
ええ、タイプのヒントがあります。したがって、メソッドが「xyzEventDispatcherインスタンス」を予期している場合は、「xyzEventDispatcherインスタンス」を渡す必要があります。知っておくと良い。
* @param array $parameters An associative array of initialization parameters
* @param array $attributes An associative array of initialization attributes
* @param array $options An associative array of options
OK。したがって、線形配列ではありません。しかし、「初期化パラメータ」を「初期化」メソッドに渡す必要があることは、私が理解できたはずです。
私が実際にそこに渡す必要があるものはまだわかりませんが、文書化されている限り、問題はありません！
* @return bool true, if initialization completes successfully, otherwise false
したがって、ブール値の戻り値は、「良い」の場合は「true」、悪い場合は「false」です。
* @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest
*/
したがって、関数の名前を実行しているときにエラーが発生すると、例外がスローされますか？
したがって、エラーの場合は例外が使用されます。 OK。知っておくと良い。
- Falseを返すことと例外を返すことの違いを教えてくれません。
- @throwsは情報を追加するので、自分自身は問題ありません
- ところで：なぜこれは太字で@リンクではないのですか
個人的には、コンストラクターでコメントするのは、特別な何か（特別な初期化など）がある場合のみです。
これが「最も便利な」方法だとは言えませんが、コードを整理し、同じことを2回繰り返す必要はありません（それが懸念事項の場合）。
個人的には、クラスとメソッドのドキュメントが最も重要なドキュメントだと思います。コードを書くとき、コード補完によってメソッドに属するドキュメントが表示されたら、IDEの助けが必要です。こうすることで、必要なメソッドを簡単に見つけることができます。
クラスの明示的な初期化を最小限に抑えようとしているので、コンストラクターのコメントは使用しません。したがって、コンストラクター自体の使用は避けようとしています。
メソッドまたは関数のコードは、宣言型変数名を使用し、それらをできるだけ小さくして、できるだけ明確にする必要があります。統合の問題など、予期しないことをした場合にのみコメントします。