2

これらの 2 つの概念は直感に反するように見えます。コメントが可読性に悪影響を及ぼし、DRY に違反している (コメントが最新の状態に保たれている場合) という意見もあります。ただし、コインを裏返すと、他のユーザーがライブラリを使用できるように、コードの適切な API ドキュメントを提供する必要があります。

API ドキュメントを生成するために設計されたすべてのツール (JSDoc、PDoc など) は、そのドキュメントを提供するために非常に多くのスペースを使用します。API ドキュメントを提供する必要がありますが、必要ではないのは、LOC の半分を特別にフォーマットされたコメントにして、JSDoc が読み取れるようにすることです。

現在、 Jekyllのような基本的なマークダウン ツールを検討しており、このドキュメントを /doc フォルダーに配置して、コードから完全に削除しています。他の誰かがこの問題へのアプローチを見つけましたか?

4

1 に答える 1

0

Sphinxは、多くの言語用のドキュメント ツールであり、ドキュメントを主に外部ファイルに記述することを前提としています。それでもautodoc、コード内のコメントからドキュメントを抽出できる拡張機能があります。

個人的には、最新の状態に保つのに役立つので、API ドキュメントをコードのすぐ近くに置く方が便利だと思います。さらに、そのコードに取り組んでいる他の人は、外部ファイルを参照することなく、必要なときにドキュメントを入手できます。率直に言って、ほとんどのコード行がコメントであることに問題があるとは思いません。エディターは通常、コメントに異なる色を付け、必要に応じてそれらを無視できるようにします。

于 2011-03-17T18:06:33.373 に答える