frama-c

[ai-review] / critic / general-error-handling.md

# Error Handling and Defensive Programming Critic Framework (Universal)

This framework guides the Critic role when evaluating code for error handling completeness, robustness, and proper error propagation strategies across all programming languages and paradigms. This critic focuses on error detection, validation, reporting, recovery, and resource management to ensure reliable, robust, and maintainable code regardless of the programming environment.

## Universal Error Handling Evaluation Areas

### 1. Error Detection and Validation
**What to Look For:**
- Comprehensive error checking at appropriate boundaries
- Proper input validation and sanitization
- Clear error detection mechanisms
- Appropriate use of assertions and preconditions
- Robust boundary condition checking
- Consistent error checking patterns

**Common Problems:**
- Missing error checks for critical operations
- Inadequate input validation
- Poor error detection mechanisms
- Missing assertions for programming errors
- Insufficient boundary condition checking
- Inconsistent error checking patterns

**Evaluation Questions:**
- Are all potential error conditions checked?
- Is input validation comprehensive and robust?
- Are error detection mechanisms clear and effective?
- Are assertions used to catch programming errors?
- Are boundary conditions properly checked?
- Is error checking consistent throughout the codebase?

### 2. Error Reporting and Communication
**What to Look For:**
- Clear, actionable error messages
- Consistent error reporting patterns
- Appropriate error detail levels
- Effective error logging mechanisms
- User-friendly error communication
- Proper error context information

**Common Problems:**
- Unclear or unhelpful error messages
- Inconsistent error reporting patterns
- Missing or inadequate error details
- Poor error logging mechanisms
- User-unfriendly error communication
- Insufficient error context

**Evaluation Questions:**
- Are error messages clear and actionable?
- Is error reporting consistent throughout the code?
- Are error details appropriate for the context?
- Is error logging effective and comprehensive?
- Is error communication user-friendly?
- Is sufficient error context provided?

### 3. Resource Management and Cleanup
**What to Look For:**
- Proper resource cleanup when errors occur
- Consistent cleanup patterns across error paths
- Appropriate use of cleanup mechanisms
- Prevention of resource leaks during error conditions
- Proper resource acquisition and release ordering
- Graceful resource degradation

**Common Problems:**
- Resource leaks on error paths
- Inconsistent cleanup patterns
- Missing cleanup in error handling code
- Improper resource ordering in cleanup
- Incomplete cleanup when multiple resources are involved
- No graceful degradation strategies

**Evaluation Questions:**
- Are resources cleaned up on all error paths?
- Is cleanup performed in the correct order?
- Are cleanup patterns consistent throughout the code?
- Are all allocated resources properly released?
- Is cleanup idempotent and safe?
- Is graceful degradation implemented?

### 4. Error Recovery and Graceful Degradation
**What to Look For:**
- Effective error recovery mechanisms
- Graceful degradation when errors occur
- Proper error state management
- Clear error recovery paths
- Robust error handling strategies
- Appropriate retry mechanisms

**Common Problems:**
- Missing error recovery mechanisms
- Poor graceful degradation
- Inadequate error state management
- Unclear error recovery paths
- Weak error handling strategies
- No retry mechanisms for transient errors

**Evaluation Questions:**
- Are error recovery mechanisms in place?
- Does the code fail gracefully when errors occur?
- Is error state managed correctly?
- Are error recovery paths clear and effective?
- Are error handling strategies robust?
- Are retry mechanisms implemented for transient errors?

### 5. Error Propagation and Consistency
**What to Look For:**
- Proper propagation of error information to callers
- Consistent error handling patterns throughout code
- Uniform error reporting mechanisms
- Standardized error recovery approaches
- Clear error handling conventions
- Predictable error behavior

**Common Problems:**
- Lost error information during propagation
- Inconsistent error handling patterns
- Non-uniform error reporting mechanisms
- Unclear error handling conventions
- Unpredictable error behavior
- Silent failures without error indication

**Evaluation Questions:**
- Is error information properly propagated to callers?
- Are error handling patterns consistent throughout the code?
- Is error reporting uniform across the codebase?
- Are error recovery approaches standardized?
- Are error handling conventions clear and followed?
- Is error behavior predictable and consistent?

## Universal Error Handling Criticism Process

### Step 1: Error Detection Analysis
1. **Evaluate Error Coverage**: Are all potential errors checked?
2. **Assess Input Validation**: Is input validation comprehensive and robust?
3. **Review Error Detection**: Are error detection mechanisms clear and effective?
4. **Check Assertions**: Are assertions used appropriately to catch programming errors?
5. **Verify Consistency**: Is error checking consistent throughout the codebase?

### Step 2: Error Reporting Assessment
1. **Audit Error Messages**: Are error messages clear and actionable?
2. **Check Error Consistency**: Is error reporting consistent throughout the code?
3. **Evaluate Error Details**: Are error details appropriate for the context?
4. **Assess Error Logging**: Is error logging effective and comprehensive?
5. **Review Error Context**: Is sufficient error context provided?

### Step 3: Resource Management Evaluation
1. **Check Resource Cleanup**: Are resources cleaned up on all error paths?
2. **Verify Cleanup Ordering**: Is cleanup performed in the correct order?
3. **Assess Cleanup Completeness**: Are all allocated resources properly released?
4. **Evaluate Graceful Degradation**: Is graceful degradation implemented?
5. **Review Resource Patterns**: Are cleanup patterns consistent throughout the code?

### Step 4: Error Recovery Analysis
1. **Review Recovery Mechanisms**: Are error recovery mechanisms in place?
2. **Check Graceful Degradation**: Does the code fail gracefully when errors occur?
3. **Evaluate Error State Management**: Is error state managed correctly?
4. **Assess Recovery Paths**: Are error recovery paths clear and effective?
5. **Review Retry Mechanisms**: Are retry mechanisms implemented for transient errors?

### Step 5: Error Propagation Assessment
1. **Check Error Propagation**: Is error information properly propagated to callers?
2. **Evaluate Consistency**: Are error handling patterns consistent throughout the code?
3. **Assess Error Conventions**: Are error handling conventions clear and followed?
4. **Review Error Behavior**: Is error behavior predictable and consistent?
5. **Check Silent Failures**: Are silent failures avoided?

## Universal Error Handling Criticism Guidelines

### Focus on Error Handling Quality
**Good Criticism:**
- "This function doesn't check for potential errors in the operation, which could lead to silent failures"
- "The error message here is unclear and doesn't provide enough information for debugging"
- "The error handling is inconsistent with the rest of the codebase and should follow the established patterns"
- "This input validation is insufficient and could allow invalid data to cause runtime errors"
- "Resource cleanup is missing in the error path, which could lead to resource leaks"

**Poor Criticism:**
- "This error handling is bad"
- "I don't like this approach"
- "This should be done differently"
- "This is not robust"

### Emphasize Robustness and Reliability
**Good Criticism:**
- "The error recovery here is inadequate and could leave the system in an inconsistent state"
- "This defensive programming is insufficient and doesn't protect against common failure modes"
- "The error boundaries are unclear, making it difficult to understand where error handling should occur"
- "The resource cleanup during errors is missing, which could lead to resource leaks"
- "Error propagation is inconsistent, making it difficult to handle errors at higher levels"

**Poor Criticism:**
- "This is not robust"
- "This is unreliable"
- "This needs to be more defensive"

### Consider Professional Standards
**Good Criticism:**
- "This violates the principle of defensive programming by not validating inputs at system boundaries"
- "The error handling doesn't follow the established patterns in this codebase"
- "The error recovery mechanism is missing, which violates the fail-fast principle"
- "This error handling is inconsistent with similar functions in the codebase"
- "The error propagation loses important context that would be needed for debugging"

**Poor Criticism:**
- "This is wrong"
- "This doesn't follow best practices"
- "This is inefficient"

## Universal Error Handling Problem Categories

### Error Detection Problems
- **Missing Checks**: Critical error conditions that are not checked
- **Inadequate Validation**: Insufficient input validation and sanitization
- **Poor Detection**: Ineffective error detection mechanisms
- **Missing Assertions**: Programming errors not caught by assertions
- **Inconsistent Checking**: Different error checking patterns for similar operations

### Error Reporting Problems
- **Unclear Messages**: Error messages that are unclear or unhelpful
- **Inconsistent Reporting**: Non-uniform error reporting patterns
- **Missing Details**: Inadequate error details for debugging
- **Poor Logging**: Ineffective error logging mechanisms
- **Missing Context**: Error messages without sufficient context information

### Resource Management Problems
- **Resource Leaks**: Failing to clean up resources on error paths
- **Inconsistent Cleanup**: Different cleanup patterns in similar contexts
- **Incomplete Cleanup**: Not cleaning up all resources when errors occur
- **Cleanup Ordering**: Incorrect order of resource cleanup operations
- **No Graceful Degradation**: Lack of graceful degradation strategies

### Error Recovery Problems
- **Missing Recovery**: No error recovery mechanisms in place
- **Poor Degradation**: Inadequate graceful degradation when errors occur
- **Resource Issues**: Poor resource cleanup during errors
- **Unclear Paths**: Unclear error recovery paths
- **No Retry Mechanisms**: Missing retry mechanisms for transient errors

### Error Propagation Problems
- **Lost Error Information**: Failing to propagate error information to callers
- **Incorrect Propagation**: Propagating errors incorrectly or inconsistently
- **Silent Failures**: Functions that fail silently without indicating errors
- **Error Masking**: Hiding or masking important error information
- **Inconsistent Patterns**: Different error handling patterns in similar contexts

## Universal Error Handling Criticism Templates

### For Error Detection Issues
```
Error Detection Issue: [Specific error detection problem]
Problem: [How this violates good error detection principles]
Impact: [Reduced reliability, maintainability, or debugging capability]
Evidence: [Specific error detection examples and principles]
Priority: [Critical/High/Medium/Low]
```

### For Error Reporting Issues
```
Error Reporting Issue: [Specific error reporting problem]
Problem: [What makes this error reporting problematic]
Impact: [Debugging, usability, or maintenance issues]
Evidence: [Specific error reporting examples and patterns]
Priority: [High/Medium/Low]
```

### For Resource Management Issues
```
Resource Management Issue: [Specific resource management problem]
Problem: [What causes the resource management issue]
Impact: [Resource leaks, crashes, or system instability]
Evidence: [Specific code paths showing resource acquisition and cleanup]
Priority: [Critical/High/Medium/Low]
```

### For Error Recovery Issues
```
Error Recovery Issue: [Specific error recovery problem]
Problem: [What makes this error recovery inadequate]
Impact: [Reliability, consistency, or user experience issues]
Evidence: [Specific error recovery examples and patterns]
Priority: [High/Medium/Low]
```

### For Error Propagation Issues
```
Error Propagation Issue: [Specific error propagation problem]
Problem: [What makes this error propagation inadequate]
Impact: [Lost error information, silent failures, or incorrect error handling]
Evidence: [Specific code examples showing propagation issues]
Priority: [Critical/High/Medium/Low]
```

## Universal Error Handling Criticism Best Practices

### Do's
- **Reference Universal Principles**: Always connect criticism to specific error handling principles
- **Focus on Error Handling Quality**: Evaluate error handling quality and professional standards
- **Consider Reliability**: Think about long-term system reliability and robustness
- **Emphasize Defensive Programming**: Prioritize code that's robust against errors
- **Provide Actionable Feedback**: Give specific suggestions for improvement
- **Consider Cross-Language Patterns**: Identify patterns that work across multiple languages

### Don'ts
- **Ignore Context**: Don't criticize without understanding the error handling context
- **Over-Engineer**: Don't suggest overly complex error handling for simple problems
- **Assume Incompetence**: Don't assume the developer is incompetent or careless
- **Skip the Why**: Don't just say something is wrong without explaining why
- **Ignore Trade-offs**: Don't suggest improvements without considering trade-offs
- **Be Language-Specific**: Don't focus on language-specific details when universal principles apply

## Universal Error Handling Criticism Checklist

### Error Detection Assessment
- [ ] Are all potential error conditions checked?
- [ ] Is input validation comprehensive and robust?
- [ ] Are error detection mechanisms clear and effective?
- [ ] Are assertions used to catch programming errors?
- [ ] Are boundary conditions properly checked?
- [ ] Is error checking consistent throughout the codebase?

### Error Reporting Assessment
- [ ] Are error messages clear and actionable?
- [ ] Is error reporting consistent throughout the code?
- [ ] Are error details appropriate for the context?
- [ ] Is error logging effective and comprehensive?
- [ ] Is error communication user-friendly?
- [ ] Is sufficient error context provided?

### Resource Management Assessment
- [ ] Are resources cleaned up on all error paths?
- [ ] Is cleanup performed in the correct order?
- [ ] Are cleanup patterns consistent throughout the code?
- [ ] Are all allocated resources properly released?
- [ ] Is cleanup idempotent and safe?
- [ ] Is graceful degradation implemented?

### Error Recovery Assessment
- [ ] Are error recovery mechanisms in place?
- [ ] Does the code fail gracefully when errors occur?
- [ ] Is error state managed correctly?
- [ ] Are error recovery paths clear and effective?
- [ ] Are error handling strategies robust?
- [ ] Are retry mechanisms implemented for transient errors?

### Error Propagation Assessment
- [ ] Is error information properly propagated to callers?
- [ ] Are error handling patterns consistent throughout the code?
- [ ] Is error reporting uniform across the codebase?
- [ ] Are error recovery approaches standardized?
- [ ] Are error handling conventions clear and followed?
- [ ] Is error behavior predictable and consistent?

## Universal Error Handling Evaluation Questions

### For Any Code
1. **Are all potential errors checked and handled?**
2. **Is error reporting clear and consistent?**
3. **Are error recovery mechanisms in place?**
4. **Is defensive programming used appropriately?**
5. **Are error boundaries clearly defined?**
6. **Is the error handling robust and reliable?**
7. **Are error messages clear and actionable?**
8. **Is error logging comprehensive and effective?**
9. **Are error patterns consistent throughout the code?**
10. **Does the code fail gracefully when errors occur?**

### For Library Code
1. **Are public error interfaces well-designed and documented?**
2. **Is error handling consistent and clear?**
3. **Are error conditions properly validated?**
4. **Is the error handling easy to use correctly?**
5. **Are all error resources properly managed?**

### For Application Code
1. **Is business logic clearly separated from error handling?**
2. **Are user inputs properly validated and sanitized?**
3. **Is error handling user-friendly and informative?**
4. **Is the error handling organized for easy maintenance?**
5. **Are error characteristics appropriate for the use case?**

## Universal Error Handling Principles Applied

### "Handle Errors Gracefully"
- Check for errors at appropriate boundaries
- Provide clear, actionable error messages
- Use consistent error handling patterns
- Fail gracefully when errors cannot be recovered from

### "Write Defensive Code"
- Validate inputs at system boundaries
- Use assertions to catch programming errors
- Assume that external data may be invalid
- Protect against common failure modes

### "Check for Errors at Boundaries"
- Validate all inputs at system boundaries
- Check for errors at appropriate interfaces
- Use assertions to catch programming errors
- Protect against common failure modes

### "Provide Clear Error Messages"
- Make error messages clear and actionable
- Provide appropriate error details for debugging
- Use consistent error reporting patterns
- Ensure error communication is user-friendly

### "Fail Fast and Gracefully"
- Detect errors as early as possible
- Fail gracefully when errors cannot be recovered from
- Provide clear error recovery paths
- Ensure robust error handling strategies

### "Manage Resources Properly"
- Clean up resources on all error paths
- Use consistent cleanup patterns
- Ensure proper resource ordering
- Implement graceful degradation

### "Propagate Errors Consistently"
- Propagate error information to callers
- Use consistent error handling patterns
- Avoid silent failures
- Maintain error context through propagation

## Universal Error Handling Quality Metrics

### Error Detection Metrics
- **Error Coverage**: All potential errors should be checked
- **Input Validation**: Input validation should be comprehensive and robust
- **Error Detection**: Error detection mechanisms should be clear and effective
- **Assertion Usage**: Assertions should be used to catch programming errors

### Error Reporting Metrics
- **Message Clarity**: Error messages should be clear and actionable
- **Reporting Consistency**: Error reporting should be consistent throughout code
- **Detail Appropriateness**: Error details should be appropriate for the context
- **Logging Effectiveness**: Error logging should be effective and comprehensive

### Resource Management Metrics
- **Resource Cleanup**: Resources should be cleaned up on all error paths
- **Cleanup Completeness**: All allocated resources should be properly released
- **Cleanup Consistency**: Cleanup patterns should be consistent throughout code
- **Graceful Degradation**: Graceful degradation should be implemented

### Error Recovery Metrics
- **Recovery Mechanisms**: Error recovery mechanisms should be in place
- **Graceful Degradation**: Code should fail gracefully when errors occur
- **Error State Management**: Error state should be managed correctly
- **Recovery Paths**: Error recovery paths should be clear and effective

### Error Propagation Metrics
- **Error Propagation**: Error information should be properly propagated to callers
- **Pattern Consistency**: Error handling patterns should be consistent throughout code
- **Error Conventions**: Error handling conventions should be clear and followed
- **Error Behavior**: Error behavior should be predictable and consistent

## Professional Standards for Error Handling

### Error Handling Standards
- **Comprehensive Checking**: All potential errors should be checked
- **Clear Reporting**: Error reporting should be clear and consistent
- **Robust Recovery**: Error recovery mechanisms should be in place
- **Defensive Programming**: Defensive coding techniques should be used effectively

### Error Communication Standards
- **Clear Messages**: Error messages should be clear and actionable
- **Consistent Patterns**: Error reporting patterns should be consistent
- **Appropriate Details**: Error details should be appropriate for the context
- **User-Friendly**: Error communication should be user-friendly

### Resource Management Standards
- **Resource Cleanup**: Resources should be cleaned up on all error paths
- **Cleanup Completeness**: All allocated resources should be properly released
- **Cleanup Consistency**: Cleanup patterns should be consistent throughout code
- **Graceful Degradation**: Graceful degradation should be implemented

### Quality Assurance Standards
- **Error Handling**: Comprehensive error checking and handling
- **Input Validation**: Validate all inputs at system boundaries
- **Resource Management**: Proper acquisition and release of error resources
- **Security Considerations**: Consider security implications of error handling