C言語は、ソースコード内にコメントを書くことができます。（「C言語の基本」を参照。）
コメントは自由に記述できますが、書き方に統一感がないと読みづらくなり、ソースコード全体の可読性が下がってしまうことがあります。
そこで今回は、ソースコード内でのコメントの書き方について、よく使われる形式や、読みやすくするためのコツを紹介します。
コメントの基本ルール
行コメント（//）// のあとに半角スペースを1つ入れます。
例）// センサー初期化
- ブロックコメント（
/* ... */）
開き/*の直後と閉じ*/の直前に 半角スペース1つ入れます。
例）/* 温度の範囲チェック */ - 複数行コメント
中の各行は先頭*の後に半角スペース1つ入れます。
例）
/*
* センサー初期化
* - I2Cリセット
* - 安定化待ち
*/- 例外
セクション見出し：枠線コメントは見た目に合わせます。
/*--------------------------------------*/
/* センサー初期化処理 */
/*--------------------------------------*/セクションコメント、または、ブロックコメントとは
処理の区切りや大まかな見出しを強調する目的で使うコメントのことです。
ファイルヘッダのコメントの書き方
C言語では、ソースファイルの先頭に「ファイルヘッダコメント」を付けるのが一般的です。
ファイルヘッダコメントには、ファイル名、機能概要、作成者、日付などを記載します。
書式（フォーマット）に厳密な決まりはありません。
開発現場やプロジェクトによってスタイルが異なりますが、ここではよく使われる一例を紹介します。
/* ============================================
* File: sensor.c
* Description: 温湿度センサー（SHT35）モジュール
* Author: Takai
* Date: 2025/11/04
* Copyright: (C) 2025 TakaiTechLab
* ============================================ */罫線や項目の数や内容に決まりはありません。
このように、ファイルの概要を先頭にまとめておくのが一般的と覚えておけば十分です。
また、「Doxygen（ドキュメント生成ツール）」という形式を使っている場合は、次のように書くこともあります。
/**
* @file sensor.c
* @brief 温湿度センサー（SHT35）モジュール
* @details I2C経由でSHT35から温湿度を取得する機能を提供します。
*
* @author Takai
* @date 2025-11-04
* @version 1.0
* @copyright (C) 2025 TakaiTechLab
* @note I2C初期化済みであることが前提です。
*/Doxygenとは、ソースコードのコメントからドキュメントを自動生成するツールです。
詳細については、別の記事で説明する予定です。
今は、「こういう書き方もあるんだな」と理解しておけば十分です。
どの形式でも共通して大切なのは、「誰が読んでも、このファイルの役割がすぐ分かるようにすること」です。
関数ヘッダのコメントの書き方
関数を定義をするときは、その直前に関数ヘッダコメントを付けるのが一般的です。
関数ヘッダコメントには、関数名、概要、戻り値、引数、注意点などを記載します。
関数の目的や使い方をひと目でわかるようにするためのものです。
書式（フォーマット）に厳密な決まりはありません。
開発現場やチームによって異なりますが、ここではよく使われる一例を紹介します。
/* --------------------------------------------
* 関数名 : read_sht35
* 概要 : 温湿度センサー（SHT35）から値を取得する
* 引数 : out_temp_c - 温度（摂氏）
* out_rh_pct - 湿度（％）
* 戻り値 : 0 成功 / 負の値 エラーコード
* 注意 : I2C初期化済みであること
* -------------------------------------------- */
int read_sht35(float *out_temp_c, float *out_rh_pct)このように、関数定義の直前にコメントを付けることで、
関数が何をするのか、どのように使うのかをすぐに理解できるようになります。
また、引数名の後に簡単な説明を添えると、よりわかりやすくなります。
また、「Doxygen（ドキュメント生成ツール）」という形式を使っている場合は、次のように書くこともあります。
/**
* @brief SHT35から温湿度を取得する
* @param[out] out_temp_c 温度（摂氏）
* @param[out] out_rh_pct 湿度（％）
* @return 0: 成功, 負の値: エラーコード
* @note I2C初期化済みであることが前提
*/どの形式でも共通して大切なのは、「誰が読んでも、この関数の役割がすぐ分かるようにすること」です。
処理にコメントを付ける
開発現場やプロジェクトによりますが、処理に付けるコメントは、「何をしているのか」を書くことが多い傾向にあります。
それは、日本語で処理内容を書いたほうが「誰が読んでもすぐに理解できる」ためです。
ただし、「何をしているか」をそのまま書くと、コードと処理内容を説明するコメントが重複しているため、コードを変更したときにコメントも修正が必要になります。
これにより、コメントも更新する必要があるため、コストが高くなったり、修正時にどちらかが古くなりやすいという問題があります。
また、日本語の方が容易に処理を理解しやすいため、コメントの方が目立つ状態になり、コード自体の可読性が下がります。
このようなことから、コメントは、「何をしているか」ではなく「なぜそうしたのか」を書いたほうが良いです。
また、「何をしているか」は、コードを見れば分かることなので、コードがわかりにくい場合だけにとどめたほうが良いです。
コメントを付ける基準
- 書くべきは理由・前提・注意点・根拠
仕様・制約など、処理の意図を説明するコメント。
安全設計上の理由。
初期化済みが前提や、割り込み中によんではいけないなどの前提。
時間がかかる処理などの注意点。
データシート参照などの根拠。 - コードを見れば分かる事実は書かない
「i を 1 増やす」「温度を読む」などは不要（命名と構造で伝える） - 変更に強いコメントにする
ふわっとした意図ではなく、根拠（資料名・ページ・URLや章）を残す。TODO:/FIXME:/NOTE:などのタグを使って検索性を上げる。 - コメントはコードの一部
変更時に必ず見直す（レビュー対象）。コードと矛盾させない。
コメントの付ける位置
コメントをどこに書くかによって、ソースコードの読みやすさは大きく変わります。
ここでは、処理にコメントを付けるときの一般的な位置と、読みやすく保つための考え方を解説します。
基本ルール
- ブロックや複数行の処理を説明するときは、処理の上に書く
- 1行で完結する軽い補足は、処理の右側に書く
- コメントが長くなる場合や重要な注意点は、必ず上に書く
処理の上に書くコメント
- まとまった処理の説明（複数行にわたる処理）
- 条件やループの目的を説明したいとき
- 処理の“意図”や“注意点”を残したいとき
例）
// センサーの初期化と安定化待ち
init_sensor();
delay_ms(100); // 100ms待機（データシートP.42参照）
// 測定値の取得と範囲チェック
read_sht35(&temp, &hum);
if ((temp < -40.0f) || (temp > 125.0f)) {
return RET_E_RANGE; // 実測範囲外
}このように、「ひとまとまりの処理の意図」を上に書いておくと、あとから読む人が“コードを追う前に目的を理解できる”ため、理解しやすくなります。
処理の右に書くコメント
- 1行で完結する軽い補足
- その行にだけ関係する注意点や根拠
- 値・式・マジックナンバーなどの補足説明
例）
delay_ms(100); // データシートでは80ms以上必要（安全側で100ms）
if (flag) return RET_E_TIMEOUT; // タイムアウト時は即終了右側コメントは、短く・簡潔にが鉄則です。
1行を越えるようなコメントや複数の情報を書くと、読みにくくなります。
位置を整える
コメントの位置を整える目的は、読みやすさと統一感の維持です。
コード自体のロジックが複雑でなくても、コメントの位置がバラバラだと全体が読みにくく感じてしまいます。
ここでは、開発現場でよく使われる整え方と、その考え方を紹介します。
- コードとコメントの間隔
コードの横にコメントを書く場合、基本的には2〜3文字分のスペースを空けると読みやすいです。
ただし、列を揃えたいときや可変長の変数名が多いときは柔軟に調整するとよいでしょう。
int temp_c = 25; // 温度（摂氏）
int humid_pct = 40; // 湿度（％）
int co2_ppm = 600; // CO2濃度（ppm）コメントが近すぎると詰まって見えてしまいます。また、離れすぎると行が横に広くなり読みにくいです。
2〜3スペースを目安に、“見た目で自然な距離感”を意識するのがコツです。
- 行を揃えるかどうか
これは現場で意見が分かれるポイントです。
| スタイル | 特徴 | 向いているコード |
| 揃える | 見やすく、処理のまとまりが把握しやすい | 変数初期化や定数定義など |
| 揃えない | 修正時の差分が少なく保守しやすい | 複数行の処理や条件分岐が多い関数内 |
※揃えない場合の特徴「修正時の差分が少ない」とは、
揃えた場合、修正時にコードが長くなってしまうと、コメントの開始位置が変更になり、それに合わせて、他の行のコメントの位置も修正が必要になってしまい、修正量が多くなります。
その点、揃えない場合は、他の行のコメントの位置を意識する必要はないので、保守しやすいということです。
- 複数行コメントの書き方（ // or /* ... */ ）
どちらのスタイルも複数行コメントに使われますが、それぞれ向き・不向きがあります。
| 形式 | 特徴 | 向いているコード |
// （行コメント） | 行単位で読みやすい。崩れにくい。 | 1～2行程度の補足 |
/* ... */ | 複数行をひとまとめにできる。目立たせたいときに便利。 | 処理のまとまりや注意点の明示、セクション（ブロック）コメントで使用 |
// を使う例
// センサー起動後の安定化待ち
delay_ms(100);
// 初回読み取りは捨てる（無効値の可能性あり）
read_sensor();/* ... */ を使う例
/* -----------------------------------------
* センサー初期化処理
* - デバイスリセット
* - 安定化待ち
* - ゴミデータの破棄
* ----------------------------------------- */
init_sensor();
delay_ms(100);
read_sensor();- 位置を整えるについてのまとめ
良いと考えている例を紹介します。
/*-----------------------------------------
* センサーの初期化と安定化
*-----------------------------------------*/
int temp_c = 0; // 温度
int humid_pct = 0; // 湿度
int co2_ppm = 0; // CO2濃度
// 起動後の安定化待ち（DS P.42）
delay_ms(100);
// 初回のゴミデータを捨てる
read_sensor();
// 範囲外データはエラー扱い
if ((temp_c < -40.0f) || (temp_c > 125.0f)) {
return RET_E_RANGE; // 実測値に基づく閾値
}このように、「セクションコメント」「軽い右側コメント」「整列ルール」が組み合わさると、
見た目が整っていても、無理がないバランスになります。
まとめ
- コメントはソースコードを理解しやすくするための補足情報であり、書くこと自体が目的ではありません。
- ファイルヘッダコメントでは、ファイルの概要・作成者・日付・注意事項などを記載し、「このファイルが何をするものか」を最初に示します。
- 関数ヘッダコメントでは、関数の目的・引数・戻り値・注意点などを記載し、関数の使い方をひと目で分かるようにします。
Doxygen形式を採用すれば、自動ドキュメント化にも対応できます。 - 処理に付けるコメントは、「何をしているか」ではなく、「なぜそうしているか」「どんな前提や注意があるか」を書くことを意識しましょう。
- コメントの位置は、下記が基本です。
- ブロック単位の説明 → 処理の上に記述
- 1行補足 → 処理の右側に短く記述
- 長い説明や注意点 → 処理の上に記述
- コメントの見た目を整える際は、コードとの間に2〜3スペースを空けるなど、読みやすさを意識します。
短い連続行では揃えると見やすくなりますが、長い関数では揃えずに書いたほうが保守しやすく、差分管理も楽です。 - セクションコメント（/*/）は、大きな処理の区切りや構造を示す目的で使うと効果的です。
- コメントとコードは常にセットでメンテナンスすることが重要です。コードを変更したら、コメントも必ず見直しましょう。