JavaScript関数のコメント/ドキュメントにそれほど多くの情報を含める必要があるのはなぜですか？
私はJavaScriptの適切なコメントの実践を調査しており、非常に高い回答（+100）がJSDocのようなコメントを引用しています。 JSDocは次のようなコメントを推奨しています。
/**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {
}
私の理解から、良いコメントは「なぜ」ではなく「なぜ」を説明する必要があり、上記は「何」の多くのように見えます。
なぜJavaScriptはこのようにコメント/文書化されるべきなのか、そしてこれは人気のある「なぜ、ではなく」コメントポリシーとどのように関連しているのですか？
内部コメントの対象読者はコード管理者です。コードのメンテナーは、コード自体から「何」を伝えることができるはずです。
外部コメントの対象読者はコードの消費者です。コードの利用者は、コードを編集するのではなく使用しているため、「なぜ」を気にしません。したがって、外部コメントは「何を」と答える傾向があります。コードの利用者は、どの関数がどのように機能するかではなく、呼び出す関数を理解する必要があるため、非常に明確なドキュメントが必要です。
これはではないコメントです。 ECMAScriptは言語機能としてのドキュメントをサポートしていないため、コメント内に記述されているドキュメントです。
このような「ドキュメントのコメント」は「通常の」コメントとは根本的に異なることに注意してください。コメントはパーサーによって無視され、コンパイラー/インタープリターの後の段階に到達することすらありません。それらは本質的に空白です。
ただし、ドキュメントのコメントはある処理されます。これらはコンパイラー/インタープリターでは処理されませんが、= IDEまたは静的アナライザーで処理されます（そして、ドキュメントジェネレーターも当然です）。
JSDocは、コードとは別に読み取られるドキュメントを生成することを目的としています。コードが自己文書化されている場合でも、コードへのアクセス権がある場合とない場合があるため、生成された文書の読者には役立ちません。
他の回答に加えて、ソースファイルまたはライブラリファイルからのコード補完機能を支援できるIDEにも役立ちます。ただし、これはどの言語にも当てはまります。