3

私はジョージア工科大学のソーラージャケットと呼ばれるチームと協力しており、「コメントの危機」に直面しています。卒業してコメントのないコードを残しているメンバーがたくさんいます。これが起こらないように、コメント標準を実装しようとしています。すべてのベースを確実にカバーするために、いくつかの提案が必要です。

私が欲しいのは次の機能です：

  • インクルード、引数、リターンタイプ、コードの一般的な説明など、すべての関数の説明を表示できる統合された場所。（コード内のコメントから生成されます）

  • コード自体では、行ごとの（またはそれに近い）説明。

私が省略したかもしれないものの提案はありますか？コードコンパイルを自動的に生成できるプログラムはありますか？プログラマーにとってこれを簡単にするにはどうすればよいですか？

4

4 に答える 4

9

あなたが説明することは私にDoxygenを思い出させます。関数、パラメーター、変数など、コード内のすべてのエンティティにコメントを付けるための形式があります。Doxygenによって生成された警告をチェックすることで、すべてが文書化されていることを強制するために使用できます。HTML、LaTeX、PDFなどのさまざまな形式でソースコードから完全なドキュメントを生成します。

多くのIDEはDoxygenタグを知っており、開発者がコードにコメントするのを支援するためにDoxygenと統合することができます。

これがDoxygenコメントの例です：

/**
 * @brief This function does blah blah.
 * @param test blah blah parameter.
 * @return 0 if blah blah passed.
 */
uint32_t TestFunction( uint32_t test )
{
    return 0;
}
于 2012-04-18T01:26:45.310 に答える
2

  • 優れたコーディング習慣を身に付けます。変数名とメソッドヘッダーは説明的であり、特にそれらが実行しているタスクに焦点を当てる必要があります。たとえば、2つの要素を交換するメソッドがある場合、それを呼び出すだけswap()で十分です。

  • DoxygenやSphinxなどのドキュメント生成ツールを使用します。

  • 読みやすさ、および何をするか（またはしないか）のガイドとして、 Java7APIなどの他のAPIを使用することをお勧めします。

おそらく、ドキュメントが多すぎると非常に気が散ることがあることを強調する必要があります。ソフトウェアの機能の専門家であるプログラマーに、ドキュメント化のために高レベルの概要を説明してもらいます。必要な場合、または必要な場合は、複雑なコードや複雑なコードを独自の用語で説明してもらいます。

于 2012-04-18T01:30:07.013 に答える
1

コードに関する行ごとの解説は悲惨に聞こえます。

  • 関数の機能を識別するために、関数の先頭にコメントが必要です。
    • パラメータなどが明確でない場合は、それらについて話し合う必要があります。
    • それ以外の場合は、できるだけ短くする必要があります。できれば1行だけにしてください。
    • 関数が複雑な場合は、より大きなコメントを付けることが適切な場合があります。判断を使用します。
  • 通常、会社またはプロジェクトのライセンスと著作権IDを含むファイルヘッダーコメントと、ファイルの全体的な目的に関するメモが必要です。
  • 定義された変数を文書化する必要があります（これは主にstatic変数である必要があります。グローバルを使用しませんか？）。
  • 関数内のコードの段落にコメントする必要がある場合があります。できれば短い（1行）コメントを付けてください。
  • 場合によっては、非自明または不明瞭なものを文書化する必要があります（おそらく関連するバグレポートを参照して）。
  • ローカル変数の定義を除いて、テールコメントが必要になることはめったにありません。

それ以外の場合、コードはそれ自体を非常に大部分説明し、コメントを不要にします。

現在のコードを説明していないコメントは迷惑であることに注意してください。昨日だけ、1990年に明確に追加されたコメントを削除しました。日付はコメントに含まれていました。特定の関数が「変数引数」をシミュレートしていた1990年の現状を説明しています。関数が7つの固定引数を持つものとして扱われるように、コードは長い間更新されていました。最後の4つは、不要な場合はnullにすることができます。したがって、コメントはもはや正確ではありませんでしたが、10年以上でした。行った。なぜ誰もそれに気づかなかったのですか？おそらく、誤ったコメントを通り越すように指導するメンターなしで、他の誰もそのファイルを初めて読んだことがないからです。または、コメントが関数から十分に削除されているためか（コメントと誤って記述された関数の間に、小さいながらも完全に別個の関数がありました）。それで、

また、同じコードに対して専門家が必要とするものと初心者が必要とするものはまったく異なる場合があることにも注意してください。どのレベルの解説が理にかなっているのかを判断する必要がありますが、コードを変更するときに、2つの説明のいずれかが適切に維持されないため、エッセイよりも質素な側で誤りを犯すことをお勧めします。維持されないのはコメントになる可能性があります。そして、誤解を招くコメントは、専門家よりも初心者にとってより悲惨です！したがって、回避可能なコメントがないために不正確なコメントを取得できないようにしてください。

于 2012-04-18T01:50:30.073 に答える
1

ここで私の新しい仕事では、コメントを最大限使用しないようにしています。コードは自己文書化する必要があります。トリッキーなコードやバグ修正などについては、いくつかの小さなコメントが許可されていますが、日常のプログラミングにはコメントがまったく含まれていません。

コードレビューセッションを使用して、すべてのチームメンバーが新しいコードを読んで学習できるようにします。コードがクリーンで読みにくい場合は、リファクタリングされます。通常、式に名前を付けるためにローカル変数を含め、変数を再利用せず、定数リテラルに#definesを追加することでうまくいきます。

于 2012-04-18T01:32:38.370 に答える