BOOLEAN_NAMING_CONVENTION

Boolean Field Naming Convention

Related Issue: #27

Overview

This document establishes the standard naming conventions for boolean fields in Alteriom packages, particularly in StatusPackage. Consistent naming patterns make the code self-documenting and help developers understand field semantics at a glance.

Three Naming Patterns

Pattern 1: *Set Suffix

Purpose: Indicates that required configuration data has been provided (typically for sensitive data like passwords or secrets).

When to use:

• Field represents whether configuration data exists
• Typically used for passwords, secrets, API keys, server URLs
• Does NOT indicate if the feature is active or working

Examples:

bool deviceSecretSet = false;  // Has device secret been configured?
bool wifiPasswordSet = false;  // Has WiFi password been provided?
bool meshPasswordSet = false;  // Has mesh password been provided?
bool otaServerSet = false;     // Has OTA server URL been configured?
bool mqttBrokerSet = false;    // Has MQTT broker been configured?

Semantic meaning:

• true = Configuration data has been provided
• false = Configuration data is missing or not yet provided
• Does NOT indicate the feature is enabled or currently working

Pattern 2: *Enabled Suffix

Purpose: Indicates that a feature is currently active or turned on.

When to use:

• Field represents a feature toggle (on/off)
• User or system can enable/disable the feature
• Feature state is controllable and intentional

Examples:

bool displayEnabled = false;           // Is display feature enabled?
bool deepSleepEnabled = false;         // Is deep sleep mode enabled?
bool mqttHourlyRetryEnabled = false;   // Is hourly retry feature enabled?
bool otaEnabled = false;               // Are OTA updates enabled?
bool encryptionEnabled = false;        // Is data encryption enabled?
bool encodingEnabled = false;          // Is data encoding enabled?
bool logTimestampEnabled = false;      // Are log timestamps enabled?

Semantic meaning:

• true = Feature is currently active/turned on
• false = Feature is currently inactive/turned off
• Independent of whether required configuration exists

Pattern 3: Runtime State (is* Prefix or *Connected)

Purpose: Indicates current runtime status or operational state (not configuration).

When to use:

• Field represents current operational status
• Status changes at runtime based on system behavior
• Not directly controlled by configuration

Examples:

bool isConfigured = false;    // Has device completed configuration?
bool mqttConnected = false;   // Currently connected to MQTT broker?
bool meshIsRoot = false;      // Is this node currently the mesh root?
bool isOnline = false;        // Is device currently online?
bool wifiConnected = false;   // Currently connected to WiFi?

Semantic meaning:

• true = Currently in this state
• false = Not currently in this state
• Reflects actual runtime conditions, not configuration

Combining Patterns

A feature may legitimately have multiple boolean fields using different patterns:

Example: OTA (Over-The-Air) Updates

bool otaServerSet = false;     // Has OTA server URL been configured? (*Set)
bool otaEnabled = false;       // Are OTA updates enabled? (*Enabled)
bool otaInProgress = false;    // Is an OTA update currently running? (is* / runtime state)

Valid states:

• otaServerSet=true, otaEnabled=false → Server configured but feature disabled
• otaServerSet=false, otaEnabled=true → Feature enabled but no server (invalid/warning state)
• otaServerSet=true, otaEnabled=true → Fully configured and active
• otaServerSet=true, otaEnabled=true, otaInProgress=true → Update in progress

Example: MQTT Connection

bool mqttBrokerSet = false;    // Has MQTT broker been configured? (*Set)
bool mqttEnabled = false;      // Is MQTT feature enabled? (*Enabled)
bool mqttConnected = false;    // Currently connected to broker? (runtime state)

Current StatusPackage Implementation

Existing *Set Fields (Build 8057)

bool deviceSecretSet = false;  // Whether device secret is configured

Potential additions (if needed):

bool wifiPasswordSet = false;  // Whether WiFi password is configured
bool meshPasswordSet = false;  // Whether mesh password is configured
bool mqttBrokerSet = false;    // Whether MQTT broker is configured
bool otaServerSet = false;     // Whether OTA server URL is configured

Existing *Enabled Fields

bool displayEnabled = false;           // Display feature enabled
bool deepSleepEnabled = false;         // Deep sleep feature enabled
bool mqttHourlyRetryEnabled = false;   // Hourly retry feature enabled

Potential additions (if needed):

bool meshEnabled = false;       // Is WiFi mesh feature enabled?
bool otaEnabled = false;        // Are OTA updates enabled?
bool encryptionEnabled = false; // Is encryption enabled?
bool encodingEnabled = false;   // Is data encoding enabled?

Potential Runtime State Fields

Currently, StatusPackage does not have explicit runtime state fields. If needed in the future:

bool isConfigured = false;      // Device has complete valid configuration
bool mqttConnected = false;     // Currently connected to MQTT broker
bool meshIsRoot = false;        // Currently acting as mesh root
bool wifiConnected = false;     // Currently connected to WiFi

Best Practices

DO ✅

1. Use *Set for configuration presence

   bool deviceSecretSet = false;  // ✅ Indicates if secret is configured

2. Use *Enabled for feature toggles

   bool displayEnabled = false;   // ✅ Indicates if feature is on/off

3. Use is* or *Connected for runtime state

   bool isConfigured = false;     // ✅ Indicates current state
   bool mqttConnected = false;    // ✅ Indicates connection status

4. Document field purpose clearly

   bool otaServerSet = false;     // Has OTA server URL been configured? (Build XXXX)

DON'T ❌

1. Don't mix patterns without clear semantics

   bool wifiSet = false;          // ❌ Ambiguous - set to what? On/off or configured?

2. Don't use generic boolean names

   bool wifi = false;             // ❌ Unclear meaning
   bool display = false;          // ❌ What about display?

3. Don't use *Set for feature toggles

   bool displaySet = false;       // ❌ Confusing - use displayEnabled instead

4. Don't use *Enabled for configuration presence

   bool deviceSecretEnabled = false;  // ❌ Confusing - use deviceSecretSet instead

Validation

When adding new boolean fields, ask these questions:

1. Does this field indicate configuration presence?

   • YES → Use *Set suffix
   • Example: mqttBrokerSet, deviceSecretSet

2. Does this field toggle a feature on/off?

   • YES → Use *Enabled suffix
   • Example: displayEnabled, otaEnabled

3. Does this field reflect current runtime state?

   • YES → Use is* prefix or *Connected suffix
   • Example: isConfigured, mqttConnected

4. Does this field fit multiple categories?

   • Consider creating separate fields for each semantic meaning
   • Example: otaServerSet AND otaEnabled AND otaInProgress

Benefits

1. Self-Documenting Code: Field names clearly indicate semantic meaning
2. Reduced Confusion: Developers immediately understand what each boolean represents
3. Better API Design: Consistent patterns across entire codebase
4. Easier Onboarding: New developers can infer meaning from field names
5. Fewer Bugs: Clear semantics reduce misunderstandings and implementation errors

References

• StatusPackage implementation: examples/alteriom/alteriom_sensor_package.hpp
• Test validation: test/catch/catch_alteriom_packages.cpp
• Time field conventions: See header documentation in alteriom_sensor_package.hpp

---

Document Version: 1.0
Last Updated: 2025-11-04
Status: Active
Applies To: StatusPackage, EnhancedStatusPackage, and all future Alteriom packages