My Guidelines for Codebase

Engineering Guidelines & Codebase Principles

This project integrates low-level hardware communication (STM32/ESP) with a high-level orchestration layer (Java 21). To ensure system reliability and maintainability, all contributors must adhere to the following principles.

1. Combatting Software Entropy

We prevent system degradation by strictly following the Broken Windows Theory: no bug or "quick fix" (workaround) should be left unaddressed.

• Avoid Rigidity & Fragility: Code must be modular. If a change in the protocol breaks the USB handler, the coupling is too high.
• Immobility Prevention: Ensure code is reusable and testable to avoid "technical debt paralysis."
• Load-Modify-Store (LMS) Awareness: Always consider the atomic nature of operations to prevent race conditions.

2. Naming Conventions & Style

We maintain a clear visual distinction between Java (Business Logic) and C (Hardware Logic).

Context	Pattern	Example
Java Classes	PascalCase	UsbPacketHandler
Java Methods/Variables	camelCase	rawUsbData
C Variables/Functions	snake_case	raw_usb_data
Global Constants	SCREAMING_SNAKE_CASE	MAX_BUFFER_SIZE

• Context-First Naming: Variables must be structured by context (e.g., EA_XX_KI, SIZE_DF_VAR).
• Enums over Magic Numbers: Use Enums with (code, description) for state machines and error codes.

3. Communication Protocols

Reliable hardware-software synchronization requires structured framing:

• Buffering: Prefer fixed-size buffers. For high-throughput requirements, implement a Circular Buffer to prevent data loss.

4. Concurrency & Threading Model

We use a Hybrid Threading Model to balance hardware latency with cloud scalability.

Java 21 Layer

• Platform Threads (Kernel Space): Dedicated to high-priority, blocking I/O (e.g., USB/Serial reading).
• Virtual Threads (User Space): Used for lightweight, concurrent tasks such as PLC connections and API processing.
• Synchronization: Prefer ReentrantLock over synchronized to avoid thread pinning in Virtual Threads.

Firmware Layer (STM32/ESP)

• Atomic Operations: Use stdatomic.h or disable IRQs during critical sections to prevent Race Conditions.
• Volatile vs. Atomic: * Use volatile for Visibility (state flags/booleans).
  • Use Atomics for Integrity (shared counters and global variables).
• Interruption Safety: Minimize variable sharing between the Main Loop and ISRs (Interrupt Service Routines).

5. Performance Optimization

• Deterministic Execution: Avoid heavy time computing inside high-frequency loops. Use modular tasks for precision.
• State Counters: Use sequential counters (cnt == 10, cnt == 11) to orchestrate non-blocking state machine actions.

6. Documentation & Quality Assurance

A "Lint-First" approach is mandatory to prevent code rot.

• Documentation: Use Doxygen for C/C++ and JavaDoc for Java.
• Static Analysis: * C/C++: Mandatory Cppcheck scans (clean report policy).
  • Java: PMD, Checkstyle, and SpotBugs for bug pattern detection.
• Automation: If code quality deviates, Linters and Formatters will be enforced via CI/CD gates.