Skip to content

Progress Log: Typedef Naming Convention Refactoring

Task Description

Audit and standardize all typedef declarations in the codebase to follow the _t suffix convention. Previously identified inconsistent naming patterns where some types use _t suffix (e.g., text_command_t, sensor_data_t) while others use CamelCase (e.g., CommandResponse, RuntimeConfig).

Scope: Rename 5 non-standard types to achieve 100% naming consistency:

  • CommandResponse → command_response_t
  • CommandHandler → command_handler_t
  • CommandEntry → command_entry_t
  • CommandAlias → command_alias_t
  • RuntimeConfig → runtime_config_t

前提知識

構造体とは

構造体（struct） は、複数の異なるデータ型をまとめて管理するための仕組みです。

例：センサーデータを管理する場合

struct sensor_data {
  int signal1;        // センサー信号1
  int signal2;        // センサー信号2
  int signal3;        // センサー信号3
  float temperature;  // 温度（℃）
};

このように関連のあるデータをひとつにまとめることで

  • コードを整理できる: 関連データを一緒に扱える
  • 保守性が上がる: どのデータがどのグループに属するか一目瞭然
  • バグが減る: データの型管理が容易になる

構造体の命名規則の慣習

プログラミングでは、コードを読む人が「これは何なのか」をすぐに理解できるような命名規則があります。

言語ごとの慣習：

  • C言語: snake_case_t（例: sensor_data_t, config_t）
  • C++/Java: CamelCase（例: SensorData, Config）

POSIX準拠:

構造体には、型名の末尾に_tをつける慣習があります。 これはPOSIX標準によって予約されており、C言語の標準ライブラリの型（int32_t, size_t, uint64_tなど）や公開インターフェイス（size_t, ptrdiff_t）などに広く使用されています。 また、POSIX準拠のシステムも公開APIで_tサフィックス型が使われています。

このプロジェクト（Arduino/ESP32）も C言語ベースの埋め込みシステムなので、 C言語の慣習にしたがって _t サフィックス を使用します。

// ✅ このプロジェクトの規則
typedef struct {
  int signal1;
  int signal2;
} sensor_data_t;  // 末尾に _t をつける

// ❌ 古い方式（避けるべき）
typedef struct {
  int signal1;
  int signal2;
} SensorData;  // CamelCase

_t とするのがいいのはどうしてか

  1. 「型である」ことを一目で認識できる
  2. sensor_data_t を見れば「これは型（type）だ」とわかる
  3. 変数 sensor_data_var と型 sensor_data_t の違いが明確
  4. 標準ライブラリとの統一性
  5. C標準ライブラリも int32_t, uint64_t など _t で型を定義している
  6. 既存コード資産との親和性が高い
  7. コード検索が簡単
  8. grep "_t" ですべての型定義を抽出できる
  9. リファクタリング時に「どこに型定義があるか」がすぐわかる
  10. バグの防止
  11. 型と変数の名前の衝突が起きにくい
  12. コンパイラエラーの原因を特定しやすい

Current State

Completed

  1. ✅ SerialCommand → text_command_t (2025-11-24)
  2. 27 occurrences across 4 files
  3. Build verified (dev profile)
  4. Commit: refactor(text-protocol): rename SerialCommand to text_command_t

Analysis Findings

Typedef Inventory (11 total):

  • _t suffix (7): serial_command_t, cosmic_detection_t, binary_command_t, text_command_t, sensor_data_t, wifi_state_t ✓
  • CamelCase (4): RuntimeConfig, CommandResponse, CommandHandler, CommandEntry ✗

Impact Assessment:

Type Occurrences Files Affected Risk
CommandResponse 51 4 files Low (mostly local vars)
CommandHandler 2 1 file (header) Minimal
CommandEntry 2 2 files Minimal
CommandAlias 2 2 files Minimal
RuntimeConfig 3 2 files Minimal

Key Findings:

  • All CamelCase types are isolated within their respective modules
  • No cross-module type dependencies
  • 51 occurrences of CommandResponse are mainly in text_protocol_handler.cpp
  • RuntimeConfig is completely self-contained in runtime_config.*
  • Changes are entirely internal (no external API impact)

Outcome

Refactoring Plan (To be executed):

Phase 1: Text Protocol Namespace (4 types)

Files to modify:

  • include/text_protocol_handler.h (4 typedef definitions + 4 references)
  • src/text_protocol_handler.cpp (37 CommandResponse occurrences + CommandEntry/CommandAlias array declarations)
  • include/text_protocol.h (2 CommandResponse references)
  • src/text_protocol.cpp (3 CommandResponse occurrences)

Changes:

  1. Typedef definitions: CommandResponse, CommandHandler, CommandEntry, CommandAlias
  2. Function return types: 14 handler functions + 2 dispatcher functions
  3. Local variable declarations: ~15 instances
  4. Array declarations: command_table[], alias_table[]

Phase 2: Configuration Namespace (1 type)

Files to modify:

  • include/runtime_config.h (1 typedef + 1 comment)
  • src/runtime_config.cpp (1 global variable)

Changes:

  1. Typedef definition: RuntimeConfig
  2. Global variable: g_config

Build Verification

  • task dev:build (text protocol with new naming)
  • task prod:build (production firmware)
  • Serial monitor test: task monitor

Learnings

Naming Convention Pattern

The codebase demonstrates a clear _t suffix convention for types:

  • Adopted consistently: text_command_t, sensor_data_t, wifi_state_t
  • No backward compatibility concerns - all type names are internal
  • No external API exposure - types are not part of public interfaces

Refactoring Safety

  • Isolated changes: No cross-module type dependencies
  • Automated replacement: sed/grep can safely rename all occurrences
  • Compile-time verification: Build process will catch any missed references
  • Low regression risk: Changes are purely mechanical (type name substitution)

Historical Context

The CamelCase types (CommandResponse, CommandHandler, etc.) appear to be remnants of earlier codebase structure before the _t suffix convention was established. The adoption of_t suffix is evident in later additions like text_command_t, sensor_data_t, and wifi_state_t.

Next Steps

  1. Execute Phase 1 refactoring (text protocol types) using sed
  2. Execute Phase 2 refactoring (runtime config type) using sed
  3. Verify compilation: task dev:build && task prod:build
  4. Create commit: refactor(types): standardize all typedef names to _t suffix
  5. Optional: Update CLAUDE.md code style section to explicitly document _t suffix convention