C言語 コメントの書き方とNG例｜プロが使うルールとサンプルコード

/* これはブロックコメントです。
 * 複数行にわたって説明を書くときに便利です。
 */
int main(void) {
    return 0;
}

int count = 0;  // ループ回数を数える

/* 外側のコメント
/* ここに別のコメントを書こうとすると */
// コンパイルエラーになる可能性が高い
*/

/* timer.c - システムタイマ制御モジュール
 *
 * 概要:
 *   - ハードウェアタイマを初期化し、周期割り込みを提供する
 *   - ミリ秒単位の遅延関数を提供する
 *
 * 注意事項:
 *   - 割り込みハンドラから呼ばれる関数は再入可能であること
 *   - マルチスレッド環境ではロックの取得順序に注意すること
 */

/* タイムアウト判定:
 * - 現在時刻が開始時刻 + 500ms を超えた場合は異常とする
 */
if (now_ms > start_ms + 500) {
    return ERR_TIMEOUT;
}

/* 仕様上の制約:
 *   - プロトコル仕様書 v1.3 の 4.2節では、
 *     パケット長は最大 32 バイトと定義されている。
 *   - そのため、バッファサイズは固定で 32 にしている。
 */
#define PACKET_BUF_SIZE  (32)

/* イベントキューの実装について
 *
 * 設計方針:
 *   - メモリフットプリントを小さくするため、固定長配列を使用する
 *   - 割り込みハンドラからもアクセスされるため、ロックは使わない
 *   - その代わり、単一プロデューサ・単一コンシューマの前提を置く
 *
 * 代替案:
 *   - リンクリスト + 動的確保は検討したが、
 *     組み込み環境での断片化リスクを避けるため採用しなかった
 */

/* タイムアウト付き読み取り関数
 *
 * 概要:
 *   指定されたファイルディスクリプタから、最大lenバイトまで読み取る。
 *   timeout_msで指定された時間内にデータが到着しない場合、タイムアウトとして扱う。
 *
 * 引数:
 *   fd         - 読み取り対象のファイルディスクリプタ(有効な値であること)
 *   buf        - 読み取りデータを書き込むバッファ(長さlen以上)
 *   len        - 読み取る最大バイト数(0より大きいこと)
 *   timeout_ms - タイムアウト時間(ミリ秒)。0の場合は即時タイムアウト。
 *
 * 戻り値:
 *   > 0  - 実際に読み取ったバイト数
 *   = 0  - EOFに到達
 *   < 0  - エラー(詳細はerrnoに設定される)
 *
 * 注意事項:
 *   - この関数はスレッドセーフではない。
 *   - ノンブロッキングモードのfdに対しては使用しないこと。
 */
ssize_t read_with_timeout(int fd, void *buf, size_t len, int timeout_ms);

/* ログファイル1行あたりの最大長(バイト)
 * 仕様上、1行の長さは最大1024バイトと決められているため、
 * バッファサイズは終端文字分を含めて1025にしている。
 */
#define LOG_LINE_MAX_LEN  (1025)

/* 現在の接続数。
 * 接続が増減するたびに、必ずこの値を更新すること。
 * 負の値にはならない前提。
 */
static int current_connection_count = 0;

int timeout_ms;    /* タイムアウト時間(ミリ秒) */
double speed_mps;  /* 速度(m/s) */

/* バブルソートによる昇順ソート
 *
 * 概要:
 *   - 配列の隣り合う要素を比較し、順序が逆であれば交換する。
 *   - これを配列の末尾まで繰り返し、末尾から順に最大値が確定していく。
 *
 * 選定理由:
 *   - 要素数が最大でも 20 個と少ないため、実装が単純なバブルソートを採用。
 *   - 安定ソートであることも条件の1つ。
 *
 * 計算量:
 *   - 時間計算量はO(n^2)
 *   - 空間計算量はO(1)
 */
void bubble_sort(int *arr, size_t n)
{
    size_t i, j;
    for (i = 0; i < n; ++i) {
        for (j = 0; j + 1 < n - i; ++j) {
            if (arr[j] > arr[j + 1]) {
                /* 隣り合う要素の順序が逆の場合に交換する */
                int tmp   = arr[j];
                arr[j]    = arr[j + 1];
                arr[j+1]  = tmp;
            }
        }
    }
}

/* TODO(2025-03-31まで):
 *   - 設定値をハードコードではなく設定ファイルから読み込むようにする
 *   - 環境変数での上書きもサポートする
 */
int max_clients = 100;  /* とりあえず固定値 */

/* FIXME(佐藤, 2025-01-15):
 *   - マルチスレッド環境でデータ競合が発生する可能性がある。
 *   - 暫定対処としてグローバルロックを使用しているが、
 *     性能劣化が大きいためロック粒度の見直しが必要。
 */
pthread_mutex_t g_lock;

/* NG例 */
int i;  // iという変数
i = 0;  // 0を代入する
i++;    // 1増やす

/* OK例 */
int retry_count = 0;  /* リトライ回数。初期値は0回 */
retry_count++;

/* 最大3回リトライする */
#define MAX_RETRY  (4)

for (int i = 0; i < MAX_RETRY; ++i) {
    /* ... */
}

/* リトライ回数:
 * - 一時的な通信エラーに対して再試行する。
 * - 実際の回数はMAX_RETRYで定義する。
 */
#define MAX_RETRY  (4)

/* NG例: 1つの段落に長文が詰め込まれている
 * この関数は、データベースからユーザ情報を取得してキャッシュに格納し、
 * もしユーザが存在しない場合にはエラーコードを返すようにしていて、
 * さらにログを出力して監査ログにも記録するようになっており...
 */

/* この関数の役割:
 *   - DBからユーザ情報を取得する
 *   - 結果をメモリキャッシュに格納する
 *   - ユーザが存在しない場合はエラーコードを返す
 *   - 監査ログにアクセス履歴を記録する
 */

/* この関数はスレッドセーフである */
static int counter = 0;

int increment_counter(void)
{
    return ++counter;  /* 実際にはロックしていない */
}

/* 現状、この関数はスレッドセーフではない。
 * 将来的にマルチスレッド対応が必要になった場合は、
 * counterへのアクセスにミューテックスを導入すること。
 */

#include <stdio.h>
#include <string.h>

/* 文字列の末尾にサフィックスを追加するユーティリティ関数
 *
 * 概要:
 *   - destの末尾にsuffixを連結する。
 *   - 連結結果がdest_sizeバイトを超える場合は、
 *     超えないところまでで切り捨てる(終端の'\0'は必ず付与)。
 *
 * 引数:
 *   dest      - 連結先バッファ。初期文字列が格納されていること。
 *   dest_size - destバッファの全体サイズ(バイト数)。
 *   suffix    - 末尾に連結したい文字列(UTF-8を想定)。
 *
 * 戻り値:
 *   0   - 成功(切り捨ての有無にかかわらず)
 *   -1  - 引数が不正(NULLポインタ、サイズ0など)
 *
 * 注意事項:
 *   - 切り捨てが発生したかどうかは戻り値では分からない。
 *     将来的に判別が必要になった場合は、別APIの追加を検討すること。
 */
int append_suffix(char *dest, size_t dest_size, const char *suffix)
{
    size_t len_dest;
    size_t len_suffix;

    if (dest == NULL || suffix == NULL || dest_size == 0) {
        return -1;
    }

    len_dest   = strlen(dest);
    len_suffix = strlen(suffix);

    if (len_dest >= dest_size - 1) {
        /* すでにこれ以上追加できないので、そのまま終了 */
        dest[dest_size - 1] = '\0';
        return 0;
    }

    /* 追加できる最大バイト数を計算する(終端の'\0'を除く) */
    size_t max_append = dest_size - 1 - len_dest;

    /* 実際にコピーするバイト数(切り捨てが発生する可能性あり) */
    size_t copy_len = (len_suffix < max_append) ? len_suffix : max_append;

    memcpy(dest + len_dest, suffix, copy_len);
    dest[len_dest + copy_len] = '\0';

    return 0;
}

int main(void)
{
    char buf[16] = "Hello";

    append_suffix(buf, sizeof(buf), ", world!");

    printf("%s\n", buf);
    return 0;
}

#include <stdio.h>
#include <errno.h>
#include <string.h>

/* 設定ファイルを開き、FILEポインタを返す
 *
 * エラー時の扱い:
 *   - ファイルが存在しない場合(ENOENT):
 *       デフォルト設定で起動し、警告ログのみ出力する。
 *   - 権限エラー(EACCESなど):
 *       起動を中止し、ユーザにメッセージを表示する。
 */
FILE *open_config_file(const char *path)
{
    FILE *fp = fopen(path, "r");
    if (fp == NULL) {
        int err = errno;

        if (err == ENOENT) {
            /* 設定ファイルが存在しない場合:
             *   - デフォルト設定で起動することを想定。
             *   - ログレベルWARNで警告を出しておく。
             */
            fprintf(stderr,
                    "Warning: config file '%s' not found. "
                    "Using default settings.\n",
                    path);
            return NULL;
        }

        /* それ以外のエラーは致命的とみなし、起動を中止する。 */
        fprintf(stderr,
                "Error: failed to open config file '%s': %s\n",
                path, strerror(err));
        return NULL;
    }

    return fp;
}

#include <stdint.h>

/* タイマーモジュールのベースアドレス
 * Datasheet: XYZ Microcontroller Timer v2 (Table 3-1)
 */
#define TIMER_BASE_ADDR   (0x40000000UL)

/* タイマー制御レジスタ(TCR)のオフセット
 *   bit0: enable (1=有効, 0=無効)
 *   bit1: mode   (0=one-shot, 1=periodic)
 *   bit2: irq_en (1=割り込み有効, 0=無効)
 */
#define TIMER_TCR_OFFSET  (0x00U)

/* タイマー周期レジスタ(TPR)のオフセット
 *   - 単位は1クロックサイクル
 *   - 実際のタイマー周期は TPR / Fclk で決まる
 */
#define TIMER_TPR_OFFSET  (0x04U)

#define TIMER_TCR   (*(volatile uint32_t *)(TIMER_BASE_ADDR + TIMER_TCR_OFFSET))
#define TIMER_TPR   (*(volatile uint32_t *)(TIMER_BASE_ADDR + TIMER_TPR_OFFSET))

/* 1ms間隔でタイマー割り込みを発生させる初期化関数
 *
 * 引数:
 *   sys_clk_hz - システムクロック周波数(Hz)
 */
void timer_init_1ms(uint32_t sys_clk_hz)
{
    /* 1ms分のカウント値を計算
     *   例: sys_clk_hz = 48MHz の場合、48,000カウントで1ms
     */
    uint32_t counts_per_ms = sys_clk_hz / 1000U;

    TIMER_TPR = counts_per_ms;

    /* タイマー有効 + 周期モード + 割り込み有効 */
    TIMER_TCR = (1U << 0) | (1U << 1) | (1U << 2);
}