v0.7.13 - -t

docs/debug_system.md

@@ -238,6 +238,162 @@ DEBUG_TRACE("Entering handle_req_message()");
 DEBUG_TRACE("Subscription ID validated: %s", sub_id);
 DEBUG_TRACE("Exiting handle_req_message()");
 ```
+## Manual Guards for Expensive Operations
+
+### The Problem
+
+Debug macros use **runtime checks**, which means function arguments are always evaluated:
+
+```c
+// ❌ BAD: Database query executes even when debug level is 0
+DEBUG_LOG("Count: %d", expensive_database_query());
+```
+
+The `expensive_database_query()` will **always execute** because function arguments are evaluated before the `if` check inside the macro.
+
+### The Solution: Manual Guards
+
+For expensive operations (database queries, file I/O, complex calculations), use manual guards:
+
+```c
+// ✅ GOOD: Query only executes when debugging is enabled
+if (g_debug_level >= DEBUG_LEVEL_DEBUG) {
+    int count = expensive_database_query();
+    DEBUG_LOG("Count: %d", count);
+}
+```
+
+### Standardized Comment Format
+
+To make temporary debug guards easy to find and remove, use this standardized format:
+
+```c
+// DEBUG_GUARD_START
+if (g_debug_level >= DEBUG_LEVEL_DEBUG) {
+    // Expensive operation here
+    sqlite3_stmt* stmt;
+    const char* sql = "SELECT COUNT(*) FROM events";
+    int count = 0;
+    if (sqlite3_prepare_v2(g_db, sql, -1, &stmt, NULL) == SQLITE_OK) {
+        if (sqlite3_step(stmt) == SQLITE_ROW) {
+            count = sqlite3_column_int(stmt, 0);
+        }
+        sqlite3_finalize(stmt);
+    }
+    DEBUG_LOG("Event count: %d", count);
+}
+// DEBUG_GUARD_END
+```
+
+### Easy Removal
+
+When you're done debugging, find and remove all temporary guards:
+
+```bash
+# Find all debug guards
+grep -n "DEBUG_GUARD_START" src/*.c
+
+# Remove guards with sed (between START and END markers)
+sed -i '/DEBUG_GUARD_START/,/DEBUG_GUARD_END/d' src/config.c
+```
+
+Or use a simple script:
+
+```bash
+#!/bin/bash
+# remove_debug_guards.sh
+for file in src/*.c; do
+    sed -i '/DEBUG_GUARD_START/,/DEBUG_GUARD_END/d' "$file"
+    echo "Removed debug guards from $file"
+done
+```
+
+### When to Use Manual Guards
+
+Use manual guards for:
+- ✅ Database queries
+- ✅ File I/O operations
+- ✅ Network requests
+- ✅ Complex calculations
+- ✅ Memory allocations for debug data
+- ✅ String formatting with multiple operations
+
+Don't need guards for:
+- ❌ Simple variable access
+- ❌ Basic arithmetic
+- ❌ String literals
+- ❌ Function calls that are already cheap
+
+### Example: Database Query Guard
+
+```c
+// DEBUG_GUARD_START
+if (g_debug_level >= DEBUG_LEVEL_DEBUG) {
+    sqlite3_stmt* count_stmt;
+    const char* count_sql = "SELECT COUNT(*) FROM config";
+    int config_count = 0;
+    
+    if (sqlite3_prepare_v2(g_db, count_sql, -1, &count_stmt, NULL) == SQLITE_OK) {
+        if (sqlite3_step(count_stmt) == SQLITE_ROW) {
+            config_count = sqlite3_column_int(count_stmt, 0);
+        }
+        sqlite3_finalize(count_stmt);
+    }
+    
+    DEBUG_LOG("Config table has %d rows", config_count);
+}
+// DEBUG_GUARD_END
+```
+
+### Example: Complex String Formatting Guard
+
+```c
+// DEBUG_GUARD_START
+if (g_debug_level >= DEBUG_LEVEL_TRACE) {
+    char filter_str[1024] = {0};
+    int offset = 0;
+    
+    for (int i = 0; i < filter_count && offset < sizeof(filter_str) - 1; i++) {
+        offset += snprintf(filter_str + offset, sizeof(filter_str) - offset,
+                          "Filter %d: kind=%d, author=%s; ",
+                          i, filters[i].kind, filters[i].author);
+    }
+    
+    DEBUG_TRACE("Processing filters: %s", filter_str);
+}
+// DEBUG_GUARD_END
+```
+
+### Alternative: Compile-Time Guards
+
+For permanent debug code that should be completely removed in production builds, use compile-time guards:
+
+```c
+#ifdef ENABLE_DEBUG_CODE
+    // This code is completely removed when ENABLE_DEBUG_CODE is not defined
+    int count = expensive_database_query();
+    DEBUG_LOG("Count: %d", count);
+#endif
+```
+
+Build with debug code:
+```bash
+make CFLAGS="-DENABLE_DEBUG_CODE"
+```
+
+Build without debug code (production):
+```bash
+make  # No debug code compiled in
+```
+
+### Best Practices
+
+1. **Always use standardized markers** (`DEBUG_GUARD_START`/`DEBUG_GUARD_END`) for temporary guards
+2. **Add a comment** explaining what you're debugging
+3. **Remove guards** when debugging is complete
+4. **Use compile-time guards** for permanent debug infrastructure
+5. **Keep guards simple** - one guard per logical debug operation
+
 
 ## Performance Impact