web-dev-qa-db-ja.com

C ++関数のコメントのベストプラクティス

関数をコメントするための受け入れられたベストプラクティスはありますか？私はdoxygenスタイルしか知っていませんが、JavadocsがJavaのために最適であると思っているように、C++によって公式にサポートされていません。

c++coding-stylecomments
51
1337

ほとんどの人が同意する一般的なことは、コメントが「何を」ではなく「なぜ」と言うことです。それ以外のガイドラインは、職場のコーディング標準に依存します。

個人的には、私が言った最初のことと矛盾するので、私はdoxygenなどを嫌います。 「ドキュメント」は、それを呼び出すことができる場合、単なるヘッダーファイルです。そして費用は？ほぼ重複したコード、目障りなコメント（真剣に、すべての高さを2倍にします）、そしてただの痛み。

コードは自己記述的である必要があります。わかりやすい名前を使用し、すべてを明確に定義されたタスクに含めるなど、コメントは明確にする必要があるものだけにしてください。

たとえば、私が書いたネットワークソケットクラスからの抜粋：

const bool socket_connected(void) const;

この関数が何をするのか既に知っています。説明する必要はありません。ソケットが接続されている（duh）ことを示すブール値（duh）を返すことを説明するコメントの大きなチャンクを本当に追加する必要がありますか？いいえ。doxygenはヘッダーを取得して、そこにちょっとしたスタイルシートを追加します。

以下に、簡単なメモが役立つ場合の例を示します（このクラスを作成します）。

struct fancy_pants
{
    // doesn't transfer ownship, ensure foo stays alive
    fancy_pants(foo&);
};

これで、fooが渡されることを確認する必要があることは明らかです。これは私のコードのu化を必要としませんでした。ドキュメントを作成する場合は、Boostのように、理論的根拠、使用目的、「落とし穴」、例などを記述したドキュメントを作成する必要があります。

ただし、すべてのヘッダーの上部に著作権ブロックがあります。これはクラスについてのほんの少しの情報を書くのに素晴らしい場所だと思います。例えば、 is_same.hpp：

/*-------------------------------------------------------
                    <copyright notice>

Determine if two types are the same. Example:

template <typename T, typename U>
void do_something(const T&, const U&, bool flag);

template <typename T, typename U>
void do_something(const T& t, const U& u)
{
    do_something(t, u, is_same<T,U>::value);
}

---------------------------------------------------------*/

それは一目で簡単なデモを提供します。上記で述べたように、それ以外のものは文書ファイルにあります。

しかし、おわかりのように、ほとんどの部分でコード標準を作成することができます。とにかく、企業では通常、標準に従う必要があります。

47
GManNickG

Visual C++ドキュメントタグ が推奨するMSDNに固執します。 MSDNは公式のドキュメントと考えています。

例：

/// <summary>Sorts the list to by the given column</summary>
/// <param name="sel">Column to be sorted (index-1-based) and sort direction (pos. = ascending)</param>  
/// <returns>Documentation of return type</returns>  
void CExamlist::SetSorting(int sel) { ... }

ReSharper C++によって解釈される

enter image description here

Visual Studio 2012+は Intellisenseに表示されるC++コメントの書き方 に従ってこれらのコメントも解釈します。

CppTripleSlash は、「///」を入力した後に正しいXMLタグを追加する優れた無料のVSプラグインです。この機能は、Visual StudioのC＃エディターから移植されています。

6
OneWorld

C++の背後には会社がないため、「公式」にサポートされるものはありません。

ご覧のとおり、doxygenは多くの異なるブロックをサポートしています http://www.doxygen.nl/docblocks.html

私は他の推奨事項の近くにとどまることを好みます。 javadocのベストプラクティスに近づこうとしています

6
X-Blaster

コメントのために Googleスタイル に従うことができます。

関数宣言のコメントで言及することの種類：

  • 入力と出力は何ですか。
  • クラスメンバー関数の場合：オブジェクトがメソッド呼び出しの期間を超えて参照引数を記憶しているかどうか、およびそれらを解放するかどうか。
  • 関数が、呼び出し元が解放する必要があるメモリを割り当てる場合。

  • 引数のいずれかがNULLになる可能性があるかどうか。

  • 関数の使用方法にパフォーマンスの影響がある場合。

  • 関数が再入可能な場合。同期の前提は何ですか？

6
codaddict

Google Standardsとは別に、このガイドは Edward Parrish によって非常に便利であることがわかりました！

ブロックコメントの例：

/**
    CS-11 Asn 2
    checks.cpp
    Purpose: Calculates the total of 6 checks

    @author Ed Parrish
    @version 1.1 4/10/16 
*/

または機能コードのコメント：

/**
    Encodes a single digit of a POSTNET "A" bar code.

    @param digit the single digit to encode.
    @return a bar code of the digit using "|" as the long
    bar and "," as the half bar.
*/

Doxygenより冗長ではなく、最小限に抑えます。詳細については、リンクを確認してください。

2
BugShotGG

「最高の」スタイルというものはないと思います。あなたに合ったものを使うべきです。コードの目的によって大きく異なります。パブリックライブラリAPIは、このようなコメントを最も必要とします。一方、実装クラスのプライベートメソッドはおそらく、自己文書化に依存している可能性があります。通常、コメントは間違っている/古いコメントよりも優れているためです。

ところで、Doxygenはいくつかのスタイルをサポートしていますが、Javadocはその1つです。

2
Alex Jenter

コメントするためのアドバイスがたくさんあるので、 Code Complete に章全体があります。 JavadocsとDoxygenスタイルは、ドキュメントの自動生成にも対応していることに注意してください。彼らが奨励したものは通常大丈夫です。

重要なアドバイスは次のとおりです。

  1. コメントは、あなたがしていることではなく、理由を説明する必要があります

  2. コメントは、保守および入力しやすい形式にする必要があります。幻想的なアスキーヘッダーとアートはありません！

2
Extrakun