Skip to content

v1.8.7 - Typedef Naming Convention Standardization (2025-11-24)

What Changed?

This release standardizes all typedef declarations across the codebase to follow the _t suffix convention, achieving 100% naming consistency. Six type renames transform legacy CamelCase types into snake_case_t equivalents. This aligns with C language standards (POSIX), standard library conventions, and existing project patterns, improving code readability and maintainability.

What's New

Main Feature: Unified Typedef Naming Convention

What it does: Standardizes all type definitions to use the _t suffix (e.g., command_response_t, runtime_config_t), which is the C language convention for typedef names. This creates consistency throughout the codebase and aligns with C standard library practices (POSIX).

Why it matters:

  • Type recognition: sensor_data_t immediately identifies a type vs. variable
  • Standard alignment: Matches C standard library (int32_t, size_t, uint64_t)
  • Code searchability: grep "_t" finds all typedef definitions
  • Maintenance: Reduces naming confusion and potential bugs

Before v1.8.7:

// Inconsistent naming (legacy CamelCase)
typedef struct { ... } SerialCommand;      // ❌
typedef struct { ... } CommandResponse;    // ❌
typedef struct { ... } RuntimeConfig;      // ❌

// Already modern (snake_case_t)
typedef struct { ... } text_command_t;     // ✓
typedef struct { ... } sensor_data_t;      // ✓

After v1.8.7:

// Uniform naming (all _t suffix)
typedef struct { ... } text_command_t;         // ✓ (renamed from SerialCommand)
typedef struct { ... } command_response_t;     // ✓ (renamed from CommandResponse)
typedef struct { ... } command_handler_t;      // ✓ (renamed from CommandHandler)
typedef struct { ... } command_entry_t;        // ✓ (renamed from CommandEntry)
typedef struct { ... } command_alias_t;        // ✓ (renamed from CommandAlias)
typedef struct { ... } runtime_config_t;       // ✓ (renamed from RuntimeConfig)

Installation

Quick Start

# Get the release
git checkout v1.8.7

# Build
task build

# Upload
task upload

# Verify it works
task monitor

What's Different from the Last Version?

✅ Added

  • Comprehensive typedef naming documentation in progress logs (docs/progress/entries/2025-11-24-typedef-naming-refactor.md)
  • Educational content explaining C struct conventions and POSIX _t suffix standards

🔧 Changed

Typedef Renames (6 types affected across text protocol and configuration modules):

  • SerialCommand → text_command_t (27 occurrences across 4 files)
  • CommandResponse → command_response_t (51 occurrences across 4 files)
  • CommandHandler → command_handler_t (2 occurrences in 1 file)
  • CommandEntry → command_entry_t (2 occurrences across 2 files)
  • CommandAlias → command_alias_t (2 occurrences across 2 files)
  • RuntimeConfig → runtime_config_t (3 occurrences across 2 files)

Affected Files:

  • include/text_protocol_handler.h - 4 typedef definitions
  • src/text_protocol_handler.cpp - 37 references
  • include/text_protocol.h - 2 references
  • src/text_protocol.cpp - 3 references
  • include/runtime_config.h - 1 typedef + comments
  • src/runtime_config.cpp - 1 global variable

🐛 Fixed

  • N/A (Refactoring release with no bug fixes)

Is It Safe to Upgrade?

Backward Compatible: Mostly ✅

  • Text protocol users: No changes to functionality, only internal type naming
  • Binary protocol users: No changes
  • Configuration: No changes to runtime behavior
  • Serial output: Unchanged format
  • Build system: task build and task upload work identically
  • Note: Internal type names changed; only relevant if you have custom code directly referencing these typedef names

Tests Passed

  • ✅ Builds without errors (all 3 environments: dev, debug, release)
  • ✅ RAM usage: 7.3% - No regression
  • ✅ Flash usage: 24.0% - No regression
  • ✅ No new compiler warnings or errors
  • ✅ Serial communication stable (text and binary protocols tested)

Code Quality Improvements

Naming Consistency

  • 100% typedef coverage: All 11 type definitions now use _t suffix
  • Standards alignment: Matches C standard library and POSIX conventions
  • Improved searchability: grep "_t" finds all typedef definitions
  • Reduced cognitive load: Clear visual distinction between types and variables

Educational Value

  • Progress log includes comprehensive explanation of C naming conventions
  • Documentation of POSIX _t suffix reservation and industry practices
  • Examples comparing legacy vs. modern naming patterns

Commits Included

Hash Message
aec98ba refactor(text-protocol): rename SerialCommand to text_command_t
9989681 refactor(text-protocol): rename CommandResponse to command_response_t
ff6604a refactor(text-protocol): rename CommandHandler to command_handler_t
9a8339e refactor(text-protocol): rename CommandEntry and CommandAlias to _t suffix
eb3f7f6 refactor(config): rename RuntimeConfig to runtime_config_t
fcf36f3 docs(progress): add beginner-friendly struct and naming convention explanations
ea7afdd docs(progress): add POSIX reservation note to typedef naming explanation
72e2974 docs(progress): restructure typedef naming conventions with POSIX context

Release Details

  • Date: 2025-11-24
  • Version: v1.8.7
  • Type: Refactoring (Code Quality & Consistency)
  • Files Changed: 8 (header + implementation files)
  • Commits: 8
  • Build Environments: All 3 (dev, debug, release)

Next Steps

v1.8.8 (Planned):

  • Consider updating CLAUDE.md Code Style section to explicitly document _t suffix convention
  • Evaluate if typedef naming standard should be added to project constitution

Long-term Roadmap:

  • Phase 5: Continue architectural improvements (queue optimization, detection buffering)
  • Phase 6: WiFi protocol integration with consistent naming patterns
  • Phase 7: Code generation tooling for new module implementations