@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/c/rules/universal/error-handling.md

@@ -0,0 +1,250 @@
+# Rule: Error Handling
+
+## Metadata
+- **ID**: universal-error-handling
+- **Category**: universal
+- **Severity**: ERROR
+- **Standard**: POSIX, CERT C
+- **Version**: 1.0.0
+
+## Description
+Always check return values from functions, use errno appropriately, implement proper error propagation patterns, and ensure cleanup on error paths.
+
+## Rationale
+Unchecked errors lead to undefined behavior, security vulnerabilities, and difficult-to-debug issues. Proper error handling makes code robust, maintainable, and secure.
+
+## Applies To
+- C Standards: c89, c99, c11, c17, c23
+- Categories: all
+
+## Rule Details
+
+### 1. Return Value Checking
+- Check return values from all functions that can fail
+- Never ignore return values (use `(void)` cast if intentional)
+- System calls, library functions, and custom functions
+
+### 2. errno Usage
+- Check `errno` after functions that set it
+- Save and restore `errno` in signal handlers
+- Clear `errno` before operations that may set it
+
+### 3. Error Propagation
+- Propagate errors up the call stack
+- Use consistent error codes or return values
+- Provide context with error messages
+
+### 4. Cleanup on Error Paths
+- Free allocated resources on all error paths
+- Use goto for centralized cleanup
+- Ensure consistent state on error
+
+## Examples
+
+### ✅ Good Example 1: System Call Error Checking
+
+```c
+#include <stdio.h>
+#include <errno.h>
+#include <string.h>
+
+int read_file(const char* filename, char* buffer, size_t size) {
+    FILE* file = fopen(filename, "r");
+    if (file == NULL) {
+        fprintf(stderr, "Failed to open %s: %s\n", filename, strerror(errno));
+        return -1;
+    }
+    
+    size_t bytes_read = fread(buffer, 1, size - 1, file);
+    if (ferror(file)) {
+        fprintf(stderr, "Error reading %s: %s\n", filename, strerror(errno));
+        fclose(file);
+        return -1;
+    }
+    
+    buffer[bytes_read] = '\0';
+    fclose(file);
+    return 0;
+}
+```
+
+### ✅ Good Example 2: Error Propagation with Cleanup
+
+```c
+#include <stdlib.h>
+#include <string.h>
+
+typedef struct {
+    char* name;
+    int* data;
+} Resource;
+
+int initialize_resource(Resource* res, const char* name, size_t data_size) {
+    int result = 0;
+    
+    if (res == NULL || name == NULL) {
+        return -1;
+    }
+    
+    res->name = strdup(name);
+    if (res->name == NULL) {
+        result = -1;
+        goto cleanup;
+    }
+    
+    res->data = malloc(data_size * sizeof(int));
+    if (res->data == NULL) {
+        result = -1;
+        goto cleanup;
+    }
+    
+    memset(res->data, 0, data_size * sizeof(int));
+    return 0;
+
+cleanup:
+    if (res->name != NULL) {
+        free(res->name);
+        res->name = NULL;
+    }
+    if (res->data != NULL) {
+        free(res->data);
+        res->data = NULL;
+    }
+    return result;
+}
+```
+
+### ✅ Good Example 3: errno Handling
+
+```c
+#include <errno.h>
+#include <unistd.h>
+#include <stdio.h>
+
+ssize_t safe_write(int fd, const void* buf, size_t count) {
+    ssize_t written = 0;
+    ssize_t result;
+    
+    while (written < count) {
+        errno = 0; // Clear before operation
+        result = write(fd, (char*)buf + written, count - written);
+        
+        if (result < 0) {
+            if (errno == EINTR) {
+                continue; // Interrupted, retry
+            }
+            perror("write failed");
+            return -1;
+        }
+        
+        written += result;
+    }
+    
+    return written;
+}
+```
+
+### ✅ Good Example 4: Multiple Error Paths
+
+```c
+int process_data(const char* input_file, const char* output_file) {
+    FILE* in = NULL;
+    FILE* out = NULL;
+    char* buffer = NULL;
+    int result = -1;
+    
+    in = fopen(input_file, "r");
+    if (in == NULL) {
+        fprintf(stderr, "Cannot open input: %s\n", strerror(errno));
+        goto cleanup;
+    }
+    
+    out = fopen(output_file, "w");
+    if (out == NULL) {
+        fprintf(stderr, "Cannot open output: %s\n", strerror(errno));
+        goto cleanup;
+    }
+    
+    buffer = malloc(4096);
+    if (buffer == NULL) {
+        fprintf(stderr, "Memory allocation failed\n");
+        goto cleanup;
+    }
+    
+    // Process data...
+    result = 0; // Success
+    
+cleanup:
+    if (buffer != NULL) free(buffer);
+    if (out != NULL) fclose(out);
+    if (in != NULL) fclose(in);
+    return result;
+}
+```
+
+### ❌ Bad Example 1: Ignoring Return Values
+
+```c
+void bad_file_handling(const char* filename) {
+    FILE* file = fopen(filename, "r");
+    // No null check!
+    
+    char buffer[100];
+    fread(buffer, 1, 100, file); // Ignoring return value
+    // No error checking!
+    
+    fclose(file);
+}
+```
+
+### ❌ Bad Example 2: No Error Propagation
+
+```c
+int bad_allocation(void) {
+    char* data = malloc(1024);
+    // No null check, no error return
+    strcpy(data, "test"); // Crash if malloc failed
+    return 0; // Always returns success!
+}
+```
+
+### ❌ Bad Example 3: Missing Cleanup
+
+```c
+int bad_cleanup(const char* file) {
+    char* buffer = malloc(1024);
+    FILE* f = fopen(file, "r");
+    
+    if (f == NULL) {
+        return -1; // Memory leak! buffer not freed
+    }
+    
+    // ... use buffer and file ...
+    
+    fclose(f);
+    free(buffer);
+    return 0;
+}
+```
+
+## Error Code Conventions
+
+```c
+// Use negative values for errors, 0 for success
+#define SUCCESS 0
+#define ERR_INVALID_PARAM -1
+#define ERR_NO_MEMORY -2
+#define ERR_IO_ERROR -3
+```
+
+## References
+
+- [CERT C - ERR33-C](https://wiki.sei.cmu.edu/confluence/display/c/ERR33-C.+Detect+and+handle+standard+library+errors)
+- [POSIX Error Handling](https://pubs.opengroup.org/onlinepubs/9699919799/)
+- [Linux errno man page](https://man7.org/linux/man-pages/man3/errno.3.html)
+
+## Related Rules
+
+- `universal-memory-safety` - Error handling for allocations
+- `category-systems` - POSIX error handling patterns
+

package/augment-extensions/coding-standards/c/rules/universal/header-guards.md

@@ -0,0 +1,254 @@
+# Rule: Header Guards
+
+## Metadata
+- **ID**: universal-header-guards
+- **Category**: universal
+- **Severity**: ERROR
+- **Standard**: C Standards, C++ Standards
+- **Version**: 1.0.0
+
+## Description
+Protect header files from multiple inclusion using `#ifndef/#define/#endif` pattern or `#pragma once` directive.
+
+## Rationale
+Header guards prevent multiple inclusion of the same header file, which can cause:
+- Redefinition errors
+- Increased compilation time
+- Potential ODR (One Definition Rule) violations
+- Unexpected behavior from duplicate definitions
+
+## Applies To
+- C Standards: c89, c99, c11, c17, c23
+- Categories: all
+
+## Rule Details
+
+### 1. Traditional Header Guards (#ifndef/#define/#endif)
+- Use unique guard names based on file path
+- Format: `PROJECT_PATH_FILENAME_H`
+- Place at the very beginning and end of header
+- Include all content between guards
+
+### 2. Pragma Once (Alternative)
+- Modern compilers support `#pragma once`
+- Simpler syntax, less error-prone
+- Not part of C standard but widely supported
+- Faster compilation in some cases
+
+### 3. Guard Naming Convention
+- Use uppercase letters
+- Include project/module name to ensure uniqueness
+- Replace path separators and dots with underscores
+- Add trailing `_H` or `_INCLUDED`
+
+## Examples
+
+### ✅ Good Example 1: Traditional Header Guard
+
+```c
+/**
+ * @file network_utils.h
+ * @brief Network utility functions
+ */
+
+#ifndef MYPROJECT_NETWORK_UTILS_H
+#define MYPROJECT_NETWORK_UTILS_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+// Function declarations
+int connect_to_server(const char* host, uint16_t port);
+void disconnect_from_server(int socket_fd);
+ssize_t send_data(int socket_fd, const void* data, size_t len);
+
+#endif /* MYPROJECT_NETWORK_UTILS_H */
+```
+
+### ✅ Good Example 2: Pragma Once
+
+```c
+/**
+ * @file config.h
+ * @brief Configuration constants
+ */
+
+#pragma once
+
+#define MAX_CONNECTIONS 100
+#define DEFAULT_PORT 8080
+#define BUFFER_SIZE 4096
+```
+
+### ✅ Good Example 3: Nested Path Header Guard
+
+```c
+/**
+ * @file src/core/memory/allocator.h
+ * @brief Custom memory allocator
+ */
+
+#ifndef MYPROJECT_SRC_CORE_MEMORY_ALLOCATOR_H
+#define MYPROJECT_SRC_CORE_MEMORY_ALLOCATOR_H
+
+typedef struct allocator Allocator;
+
+Allocator* allocator_create(size_t pool_size);
+void allocator_destroy(Allocator* alloc);
+void* allocator_alloc(Allocator* alloc, size_t size);
+void allocator_free(Allocator* alloc, void* ptr);
+
+#endif /* MYPROJECT_SRC_CORE_MEMORY_ALLOCATOR_H */
+```
+
+### ✅ Good Example 4: Header with External C Linkage
+
+```c
+/**
+ * @file api.h
+ * @brief Public API for C++ compatibility
+ */
+
+#ifndef MYPROJECT_API_H
+#define MYPROJECT_API_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// API functions
+int initialize_library(void);
+void shutdown_library(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* MYPROJECT_API_H */
+```
+
+### ❌ Bad Example 1: Missing Header Guard
+
+```c
+/**
+ * @file utils.h
+ */
+
+// No header guard!
+
+void utility_function(void);
+int helper_function(int x);
+```
+
+### ❌ Bad Example 2: Incomplete Header Guard
+
+```c
+/**
+ * @file data.h
+ */
+
+#ifndef DATA_H
+#define DATA_H
+
+struct Data {
+    int value;
+};
+
+// Missing #endif - will cause errors!
+```
+
+### ❌ Bad Example 3: Non-Unique Guard Name
+
+```c
+/**
+ * @file src/module_a/config.h
+ */
+
+#ifndef CONFIG_H  // Too generic, may conflict!
+#define CONFIG_H
+
+#define MAX_SIZE 100
+
+#endif
+```
+
+### ❌ Bad Example 4: Guard Doesn't Cover All Content
+
+```c
+#include <stdio.h>  // Outside guard - will be included multiple times!
+
+#ifndef UTILS_H
+#define UTILS_H
+
+void print_message(const char* msg);
+
+#endif
+```
+
+## Guard Naming Examples
+
+| File Path | Guard Name |
+|-----------|------------|
+| `utils.h` | `MYPROJECT_UTILS_H` |
+| `src/core/memory.h` | `MYPROJECT_SRC_CORE_MEMORY_H` |
+| `include/api/v2/client.h` | `MYPROJECT_INCLUDE_API_V2_CLIENT_H` |
+| `lib/network/tcp.h` | `MYPROJECT_LIB_NETWORK_TCP_H` |
+
+## Choosing Between #ifndef and #pragma once
+
+### Use #ifndef/#define/#endif when:
+- Maximum portability is required
+- Working with very old compilers
+- Project coding standards mandate it
+- Building for embedded systems with limited toolchains
+
+### Use #pragma once when:
+- Working with modern compilers (GCC, Clang, MSVC)
+- Simplicity and readability are priorities
+- Faster compilation is desired
+- Team/project standards allow it
+
+## Common Mistakes
+
+1. **Forgetting the closing #endif**
+   - Causes compilation errors
+   - Use editor features to match directives
+
+2. **Using non-unique guard names**
+   - Can cause silent bugs
+   - Always include project/module prefix
+
+3. **Placing includes before guard**
+   - Defeats the purpose of guards
+   - Guard should be first non-comment line
+
+4. **Typos in guard names**
+   - #ifndef and #define must match exactly
+   - Use copy-paste to avoid errors
+
+## Automation
+
+### Generate guard name from filename (bash):
+```bash
+#!/bin/bash
+filename="$1"
+guard=$(echo "$filename" | tr '[:lower:]' '[:upper:]' | tr './' '__')
+echo "#ifndef ${guard}"
+echo "#define ${guard}"
+echo ""
+echo "// Content here"
+echo ""
+echo "#endif /* ${guard} */"
+```
+
+## References
+
+- [C Standard - 6.10 Preprocessing directives](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf)
+- [GCC Documentation - Once-Only Headers](https://gcc.gnu.org/onlinedocs/cpp/Once-Only-Headers.html)
+- [Google C++ Style Guide - Header Guards](https://google.github.io/styleguide/cppguide.html#The__define_Guard)
+
+## Related Rules
+
+- `universal-naming` - Guard naming conventions
+- `universal-documentation` - File header documentation
+