C言語のコメントの書き方について教えてください


関数の説明を記載する場所について困っています。
公開関数のプロトタイプをまとめたヘッダファイルに関数の説明を記載するべきか
それとも、関数の実体があるソースファイルに記載するべきか迷っています
どちらも書けばいいのでしょうが2重管理になってしまうため大変そうです

ここでいう関数の説明とは
処理の概要や、引数の説明、返り値の説明などのことです


ヘッダファイルは公開するため、関数の説明記載は必須と感じています
一方、ソースファイルにもソースの可読性やメンテナンスの際の情報として
関数の説明記載は必要だと感じています

一般的には(あるいは実際の開発では)どのようにして
この問題を解消しているのでしょうか

回答の条件
  • 1人10回まで
  • 13歳以上
  • 登録:2014/02/11 17:17:57
  • 終了:2014/02/12 00:19:26

ベストアンサー

id:bg5551 No.1

bg5551回答回数1184ベストアンサー獲得回数802014/02/11 17:50:17

ポイント50pt

個人での開発か、会社などでの開発かで違ってきます。
個人なら自分が解ればいいので自分の好みで書いて構いません。
業務での開発の場合は、会社のコーディング規約に従います。
規約は絶対なので、嫌でも従うしかありません。
私の周りではソースの直前にコメントを入れるのを好む人が多いです。

id:fujimasa1985

ありがとうございます
参考になりました

2014/02/12 00:18:26

その他の回答(1件)

id:bg5551 No.1

bg5551回答回数1184ベストアンサー獲得回数802014/02/11 17:50:17ここでベストアンサー

ポイント50pt

個人での開発か、会社などでの開発かで違ってきます。
個人なら自分が解ればいいので自分の好みで書いて構いません。
業務での開発の場合は、会社のコーディング規約に従います。
規約は絶対なので、嫌でも従うしかありません。
私の周りではソースの直前にコメントを入れるのを好む人が多いです。

id:fujimasa1985

ありがとうございます
参考になりました

2014/02/12 00:18:26
id:Yacky No.2

エネゴリ回答回数1370ベストアンサー獲得回数1542014/02/11 20:14:02

ポイント50pt

業務なら指示に従わないといけませんが、個人なら自由です
一般的に下記のようなコメントが良いとされています
http://d.hatena.ne.jp/eel3/20090811/1249977594

id:fujimasa1985

ありがとうございます
参考になりました

2014/02/12 00:18:31
  • id:Yoshiya
    関数の説明をするのであれば、ソースコードの先頭に書くのが普通です。

    書式例)
    //
    // 関数名:
    //
    // 引 数:
    //
    // 戻り値:
    //
    // 説 明:
    //
    // 履 歴:
    //
    //

    ここで重要なのは、この関数のコメントを読めばプログラム仕様書が無くても理解できる様に記述するという事です。
    ローカル変数、外部変数、アルゴリズムの簡単な説明はソース内に記述します。

    上記の様な関数説明は、個人的に書くソースであれば不要若しくは簡略化できますが、業務で書くソースについては、コーディング規約に基いて記載します。
    コーディング規約に関数説明が無い場合は、統一したフォーマットを予め決めておくのがいいと思います。
  • id:fujimasa1985
    ありがとうございます
    参考になりました
  • id:tea_cup
    > どちらも書けばいいのでしょうが2重管理になってしまうため大変そうです
     せっかくコンピュータ使っているのですから、自分たちの役にも立てましょう。
     最近の開発現場知りませんが、「コメント部分を比較して更新があったら更新をかける」スクリプトをバージョン管理システムと組み合わせて使えばそんなに大変じゃないです。
     ヘッダファイルのコメントを直接書き換えちゃう人には、ルールを教育する必要がありますが。

  • id:Bookmarker
    Doxygenとか使って実装の方に書いたコメントからドキュメントを自動生成しています。

    Doxygen:
    http://www.doxygen.jp/

この質問への反応(ブックマークコメント)

「あの人に答えてほしい」「この質問はあの人が答えられそう」というときに、回答リクエストを送ってみてましょう。

これ以上回答リクエストを送信することはできません。制限について

絞り込み :
はてなココの「ともだち」を表示します。
回答リクエストを送信したユーザーはいません