Skip to content

Progress Log: Protocol Function Naming Convention (v1.8.6)

Task Description

Implement a consistent naming pattern for all protocol functions in the firmware to improve code readability, maintainability, and developer velocity when implementing new protocols. The naming convention follows the pattern [protocol]_[stage]() where:

  • [protocol]: The protocol identifier (binary or text)
  • [stage]: The processing pipeline stage (receive, queue, queued, dequeue, validate, execute, response_ok, response_error)

The standardization addressed inconsistencies in the codebase where function names were unclear about protocol type and processing stage.

Outcome

Successfully implemented and documented the [protocol]_[stage]() naming convention across all protocol functions:

Binary Protocol (binary_*)

  • binary_receive() - Read binary command from serial, validate structure, queue it
  • binary_queue() - Add binary command to queue
  • binary_queued() - Check if binary commands pending
  • binary_dequeue() - Remove next binary command from queue
  • binary_execute() - Dequeue and execute pending binary command
  • binary_validate() - Validate binary command payload and execute if valid
  • binary_response_ok(channel, data1, data2) - Send success response (JSONL format)
  • binary_response_error(error_msg, error_code) - Send error response (JSONL format)

Text Protocol (text_*)

  • text_receive() - Read text command line from serial, parse it, queue it
  • text_queue() - Add text command to queue
  • text_queued() - Check if text commands pending
  • text_dequeue() - Remove next text command from queue and execute
  • text_execute() - Dequeue and execute pending text command
  • text_parse() - Parse text command line into structured command
  • text_dispatch() - Validate and dispatch parsed command to handler
  • text_response_ok(message) - Send success response (JSONL format)
  • text_response_error(command, error_msg, error_code) - Send error response (JSONL format)

Shared Utilities

  • serial_init(baudRate) - Initialize serial communication with specified baud rate
  • serial_discard() - Discard remaining bytes from serial input buffer (safe with size limit)

Improvements Applied

  • ✅ Removed unused wrapper functions to reduce API surface
  • ✅ Renamed serial_flush() → serial_discard() for clarity (input buffer cleanup vs output flush)
  • ✅ Moved text protocol queue management to text_protocol.cpp for architectural symmetry
  • ✅ All functions now use [protocol]_[stage]() pattern consistently
  • ✅ Shared utilities clearly prefixed with serial_ (not protocol-specific)

Learnings

Benefits Realized

  1. Self-Documenting Code: Function names immediately communicate what protocol is being used and where in the pipeline the function operates
  2. Discoverability: Developers can find related functions by searching for common prefixes (binary_*, text_*, *_queue, *_response_*)
  3. Consistency Across Protocols: New protocol implementations automatically follow the same pattern, reducing cognitive load and training time
  4. Pipeline Clarity: Reading code from top to bottom shows the logical flow of command processing

Historical Context

Before v1.8.6, the codebase had inconsistent function names:

  • serial_read_command() vs serial_read_text_command()
  • process_binary_commands() vs process_text_commands()
  • send_binary_dac_response() vs send_ok_response()
  • serial_available() (unused wrapper)
  • serial_send_response() (unused wrapper)
  • serial_send_text_response() (unused wrapper)
  • serial_flush() (confusing name, unclear purpose vs Serial.flush())

These inconsistencies made it difficult to:

  • Understand which protocol a function handled
  • Find related functions
  • Follow the processing pipeline
  • Distinguish between Arduino API (Serial.flush()) and local utilities

Next Steps

  • Monitor adoption of the naming convention in new protocol implementations
  • Document additional protocols using the same [protocol]_[stage]() pattern
  • Consider adding linting rules to enforce naming convention in CI/CD pipeline
  • Update code review guidelines to reference the protocol naming convention document