コメントはドキュメントの形式と見なされますか？
自分用に小さなスクリプトを書いているときは、コードをコメントで高く積み上げています（コードよりもコメントが多い場合があります）。私が話している多くの人々は、私がこれらのスクリプトを個人的であるとしても、私はそれらを文書化するべきであると言っています。しかし、コメントはドキュメントの形式ではありませんか？
これではないでしょう：
$foo = "bar"; # this is a comment
print $foo; # this prints "bar"
特に開発者が私のコードを使用している場合、ドキュメントと見なされますか？または、ドキュメントはコード自体の外にあると見なされますか？
コメントは間違いなくドキュメントです。ほとんどのプロジェクトでは、コメントは（残念ながら）プロジェクトドキュメントの主要な（だけでなく）形式です。このため、正しく理解することが非常に重要です。コードを変更しても、このドキュメントが正確であることを確認する必要があります。これはコメントに関する一般的な問題です。開発者は、使い慣れたコードで作業しているときにそれらを「調整」することが多いため、コードを反映するためにコメントを更新するのを忘れています。これは古く、誤解を招くコメントを作成する可能性があります。
多くの人々は、コードを自己文書化することを提案しています。つまり、コメントの代わりに、コードを再構成して、コメントを不要にすることができます。これにより、「何を」および「どのように」コメントのほとんどを取り除くことができますが、「なぜ」コメントは実際には役立ちません。これはほとんどのコメントを取り除くために効果的に機能するかもしれませんが、コメントを書くことがコードの一部を文書化するための最も簡単で最も効率的な方法である多くの場合がまだあります。
それらはドキュメンテーションの一種ですが、ドキュメンテーションは見る人の目にあることを忘れないでください...
自己文書化コードで十分な人もいます。しかし、それは顧客としての技術的詳細のレベルを前提としています。私たちのエゴは「このコードが何をしているかは明らか」と言っているかもしれませんが、時間がそうでない場合は証明できるため、これで十分であると慎重に考える必要があります。また、読者のスキルを事前に知っていることも前提としています。
ソースコードを見ているが、技術的な専門知識が少ない方は、commentsで問題ありません。しかし、それは誰かがソースコードを見ていることを前提としています。
あなたが技術的だが、すべてのソースコードを読む時間が足りない場合、technical manualが必要な場合があります。
ユーザーが技術的なスキルを欠いているが、何が起こっているかを知る必要があるだけの場合user documentationが必要です。
だから本当の質問はあなたの顧客は誰ですか？もしそうなら、自己文書化コードまたはコメントで十分です。それが他の誰かを対象としている場合は、文書化の方法を広げることができます。
はい、コメントはドキュメントの形式です。それらが有用であるかどうかにかかわらず、コードを保守または更新する必要がある人のためのドキュメントは未解決の問題です。
あなたが使い捨ての例としてそれを意味したのを知っていますが、
print $foo; # this prints "bar"
役に立たない。視覚的な混乱を追加するだけです。明白な文書化しないでください。
メソッドまたは関数定義の先頭にあるコメントをブロックします。これは、関数またはメソッドの目的（高レベル用語で）、入力、出力、戻り値（ある場合）、例外（ある場合）、事前条件と事後条件は便利ですが、関数またはメソッドがどのように使用されることになっているのかを誰かに伝える程度に限られます。彼らは説明しないなぜ関数が存在するか。
他の誰かがコードを保守する必要がある場合は、要件と設計をどこかに文書化する必要があります。これは通常、ソースコード自体でnotが行われます。
Clean CodeによるBob Martinのこれへのアプローチに固執することで、通常、コメントしすぎているのか、コメント不足でドキュメントを省いているのかという問題が解決されます。
私たちは作家です。そして、作者についての1つのことは彼らが読者を持っているということです。実際、作者は読者とうまくコミュニケーションする責任があります。次にコード行を書くときは、あなたが作者であることを覚えておいてください。あなたの努力を判断する読者のために書いてください。
...読み取りと書き込みに費やされた時間の比率は10：1をはるかに超えています。新しいコードを書く努力の一環として、常に古いコードを読んでいます。
言い換えれば、あなたのコードはドキュメントがなければ自明ですか？ Microsoftのような、ドキュメントが一般に公開されている誰かのために働いているのでない限り、そのための規則はありません。多くの場合、あなたであることが多いコードの将来の読者を支援することです。
コメントはドキュメントの形式です。劣ったフォーム、およびより因数分解できるコードの領域を見つけたことを示唆するフォーム。
強引にコメントしているようですね。他のオプションを持つことは良いことかもしれません。私は3つの優れた形式のドキュメントを考えることができます。
1）コードをよりよく因数分解します。コメントを追加するのではなく、記述しようとしているコメントのテキストを名前とするメソッドまたは関数を抽出します。したがって、コードはあなたのコメントがこれから言うことを言っています。
2）テスト。これは、私が通常検索するドキュメントの形式です。単体テストと受け入れテストは生きた文書であり、ポイント1のように、意図を表現するために多くの意味のある方法が使用されている場合は、簡単に読むことができます。
3）スクリプトの場合、-helpオプション。これは、あなたがドキュメンタリーに行き詰まるところです。例に固執し、ユーザーが必要とするものを予測します。
要約すると、コメントにこだわる傾向がある場合は、コードをより適切に構造化することにより、リーダーと通信する方法があるかどうかを確認してください。または、そのコードが存在する理由を伝えるテストはありますか？それでもコメントしたいと思うなら、敗北を認めて、それを実行してください。
ドキュメントはHowではなくWhyをドキュメント化する必要があります。 Howはコード内で自明である必要があります。つまり、一般的に発生しない難解な最適化トリックやその他の言語固有の手法でない限りです。
Whyはおそらくコードに含めないでください。変更ログまたはブランチ名で検索できるストーリーIDを含むコミットコメントに関連付けられている、製品のバックログのような別の場所にする必要があります。