コメントはドキュメントの形式と見なされますか？

自分用に小さなスクリプトを作成しているときは、コードをコメントでスタックします（コードよりもコメントが多い場合があります）。私が話している人の多くは、これらのスクリプトは個人的なものであっても、文書化する必要があると言っています。しかし、コメントはドキュメントの形式ではありませんか？

これではないでしょう：

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

特に開発者が私のコードを使用している場合、ドキュメントと見なされますか？または、ドキュメントはコード自体の外にあると見なされますか？

コメントは間違いなくドキュメントです。ほとんどのプロジェクトでは、コメントは（残念ながら）プロジェクトドキュメントの主要な形式（だけでなく）です。このため、正しく理解することが非常に重要です。コードを変更しても、このドキュメントが正確であることを確認する必要があります。これはコメントに関する一般的な問題です。開発者は、使い慣れたコードで作業しているときにそれらを「調整」することが多いため、コードを反映するためにコメントを更新するのを忘れています。これにより、古くて誤解を招くコメントが作成される可能性があります。

多くの人々は、コードを自己文書化することを提案しています。つまり、コメントの代わりにコードを再構成して、コメントを不要にすることができます。これは、「何を」と「どのように」のコメントのほとんどを取り除くことができますが、「なぜ」コメントを実際には助けません。これはほとんどのコメントを取り除くために効果的に機能するかもしれませんが、コメントを書くことがコードの一部を文書化する最も簡単で最も効率的な方法である多くの場合がまだあります。

それらはドキュメンテーションの一種ですが、ドキュメンテーションは見る人の目にあることを忘れないでください...

• 一部では、自己文書化コードで十分です。しかし、それは顧客としての技術的詳細のレベルを前提としています。私たちのエゴは「このコードが何をしているかは明らかです」と私たちに告げるかもしれないが、時間がそうでなければ証明できるので、私たちはこれで十分であると慎重に考えるべきです。また、読者のスキルを事前に知っていることも前提としています。

• ソースコードを見ているが、技術的な専門知識が少ない人にとっては、コメントは大丈夫かもしれません。しかし、それは誰かがソースコードを見ていることを前提としています。

• あなたが技術的だが、すべてのソースコードを読む時間が足りない場合は、技術マニュアルが必要かもしれません。

• ユーザーが技術的なスキルを欠いているが、何が起こっているかを知る必要があるだけの場合、ユーザーのドキュメントが必要です。

だから本当の問題はあなたの顧客は誰ですか？もしそうなら、自己文書化コードまたはコメントで十分です。それが他の誰かのためのものである場合、文書化の方法を広げることができます。

はい、コメントはドキュメントの形式です。それらがあなたのコードを維持または更新しなければならない人にとって有用なドキュメントであるかどうかは、未解決の問題です。

私はあなたがそれを使い捨ての例として意味したことを知っています、しかしのようなもの

print $foo; # this prints "bar"

役に立たない。視覚的な混乱を追加するだけです。明白な文書化しないでください。

ブロック（関数やメソッドの目的を記述した方法または関数定義の先頭のコメントハイレベルの観点から）、入力、出力、戻り値（もしあれば）、例外（もしあれば）、前提条件、および事後条件は有用であり、ただし、関数またはメソッドがどのように使用されることになっているのかを誰かに伝える程度に限られます。彼らはなぜ関数が存在するのか説明していません。

他の誰かがコードを保守する必要がある場合は、要件と設計をどこかに文書化する必要があります。これは通常、ソースコード自体では行われません。

Clean CodeによるBob Martinのこれに対するアプローチに固執することで、通常、コメントしすぎているのか、コメント不足でドキュメントを省いているのかという問題が解決されます。

私たちは作家です。そして、作者についての1つのことは彼らが読者を持っているということです。実際、作者は読者とうまくコミュニケーションする責任があります。次にコード行を書くときは、あなたが作者であることを覚えておいてください。あなたの努力を判断する読者のために書いてください。

...読み取りと書き込みに費やされた時間の比率は10：1をはるかに超えています。新しいコードを書く努力の一環として、常に古いコードを読んでいます。

言い換えれば、あなたのコードはドキュメントがなければ自明でしょうか？Microsoftのように、ドキュメントが公開されている誰かのために働いているのでない限り、そのための規則はありません。ほとんどの場合、将来のコードリーダーを手助けすることになります。

ドキュメントには、なぜではないのかを文書化する必要があります。どのようには自明のコードでは、それは一般的にoccuringされていないいくつかの難解な最適化のトリックや他の言語固有の技術でない限り、あるべきです。

なぜが、おそらくコードにすべきではない、それは変更ログやブランチ名で検索することができ物語IDとコメントをコミットするために結ばれている製品バックログ、同様にどこか別の場所でなければなりません。

コメントはドキュメントの形式です。劣った形式、およびより因数分解できるコードの領域を見つけたことを示唆する形式。

強引にコメントしているようですね。他のオプションを持つことは良いことかもしれません。私は3つの優れた形式のドキュメントを考えることができます。

1）コードをよりよく因数分解します。コメントを追加するのではなく、記述しようとしているコメントのテキストを名前とするメソッドまたは関数を抽出します。したがって、コードはあなたのコメントがこれから言うことを言っています。

2）テスト。これは、私が通常検索するドキュメントの形式です。単体テストと受け入れテストは生きた文書であり、ポイント1のように、意図を表現するために多くの意味のある方法が使用されている場合は、簡単に読むことができます。

3）スクリプトの場合、-helpオプション。これは、あなたがドキュメントに夢中になれるところです。例に固執し、ユーザーが必要とするものを予測します。

要約すると、コメントにこだわる傾向がある場合は、コードをより適切に構造化することにより、リーダーと通信する方法があるかどうかを確認してください。または、そのコードが存在する理由を伝えるテストはありますか？それでもコメントしたいと思うなら、敗北を認め、それを実行してください。