コードドキュメンテーション：公開か非公開か？

私は、記述されたコードが自明であり、本のように読まれるべきであるという考え方を持っている開発者の1人です。

ただし、他の人が使用するライブラリコードを開発するときは、できるだけ多くのドキュメントをヘッダーファイルに入れるようにしています。これは質問を持ち出します：非公開のドキュメント化方法は時間の価値さえありますか？彼らはそれらを直接使用することはありませんが、実際には使用できません。同時に（しぶしぶながら）未加工のコードを配布すると、これらの非パブリックメソッドが表示され、説明が必要になる場合があります。

皆さんが旅行中に見たり使用したりする基準や慣行を探しているだけです。

「エンドユーザー」が使用しないという理由だけで、内部のドキュメントを省略することは考えません。コードのメンテナンスは、すべてのコンポーネントのドキュメントコメントを含めるのに十分な理由です。実際、特に最も複雑な（そして頻繁に変更される）傾向がある内部の場合はそうです。

とはいえ、抽象化を維持するために、それらを非公開のソースコードに限定して（公に文書化されているのではなく）維持するための有効なケースがあるかもしれません。

これはすべて主観的なことです。

わかりました。コメントやドキュメント化の方法も写真に追加して、バラエティに富みます。理論的根拠は、ヘッダーでのみ宣言されている関数またはメンバー関数の記述を避けることです。一方では、ヘッダーにノイズを追加しすぎるのを恐れています。一方、ドキュメントと定義を一緒にすると、メンテナーが一致しやすくなります。Doxygenはどちらの方法も気にせず、必要に応じてプライベートを除外できます。

クラスヘッダー：

• 含まれるヘッダー（なぜ）
• 常にクラス定義（目的と責任）
• 常に純粋仮想関数（完全契約）
• 自明のゲッターでない限りインライン関数
• 自明でない限り、他の宣言された型
• 静的データメンバー（理由）
• 自明でない限り、他のデータメンバー
• マクロがある場合（契約と理由）

クラス実装コード：

• ヘッダーと同じ方法でのローカル宣言
• 常に関数定義（完全契約）
• 常にメンバー関数定義（完全なコントラクトまたは仮想オーバーライドのルートへの参照）
• 静的変数がある場合に定義されます（目的、理由）

テンプレートヘッダー：

• 上記がマージされ、
• テンプレート引数に適した/不適切なタイプ
• 適合性が静的にどの程度検出されているか

private:プライベートセクションの冒頭には、ユーザーが必要とする必要があるすべてのドキュメントです。

ドキュメントはいつでも価値があります。ユースケースとストーリーを簡単に説明するのに役立ちます。コードがどれほど自明であるかは、物語の数行ほど簡単にはビジネスを説明できません。このコードでは、ユーザーは何が起こっているのかを理解するだけでなく、ロジックに従う必要があります。:-)私の2セント...

間違いなく！

そのコードは自己文書化する必要があります生きるためのスローガンです。しかし、私が言うには、プライベートコードはパブリックコードと同じかそれ以上の量のドキュメントを必要とします。なぜなら、コーダーが暗闇にとどまると想定しているからといって、ほとんどの仮定が通常行われるのは通常ここだからです。 。したがって、数か月後、バグが発生すると、コードの背後にあるアイデア（おそらく自分自身）が書いたものを思い出すことに時間を費やすことになります。

ドキュメンテーションは他の人への素晴らしい贈り物として存在すべきではありません。ドキュメンテーションは、そのすべての面で（適切に選択された変数名、自己文書化クラス名、適切に編成されたコード、適切にセグメント化されたメソッドなど）、自分自身を含めて、コードに接触する可能性のあるすべての人への贈り物です。