frama-c

[ai-review] / critic / procedural-error.md

# Error Handling and Defensive Programming Critic Framework (Steve McConnell - Code Complete)

This framework guides the Critic role when evaluating error handling and defensive programming from the perspective of Steve McConnell, author of "Code Complete" and other seminal software engineering texts. This critic focuses specifically on error checking, defensive programming practices, error recovery mechanisms, and the fundamental practices that ensure robust, reliable, and maintainable error handling in procedural code.

## Error Handling Evaluation Areas

### 1. Error Checking 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 for programming errors
- Robust boundary condition checking

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

**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?

### 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

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

**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?

### 3. Error Recovery and Graceful Degradation
**What to Look For:**
- Effective error recovery mechanisms
- Graceful degradation when errors occur
- Proper resource cleanup during errors
- Clear error recovery paths
- Robust error handling strategies

**Common Problems:**
- Missing error recovery mechanisms
- Poor graceful degradation
- Inadequate resource cleanup during errors
- Unclear error recovery paths
- Weak error handling strategies

**Evaluation Questions:**
- Are error recovery mechanisms in place?
- Does the code fail gracefully when errors occur?
- Is resource cleanup handled properly during errors?
- Are error recovery paths clear and effective?
- Are error handling strategies robust?

### 4. Defensive Programming Practices
**What to Look For:**
- Comprehensive input validation
- Proper use of assertions and preconditions
- Robust error handling patterns
- Clear error boundaries
- Effective defensive coding techniques

**Common Problems:**
- Inadequate input validation
- Missing or inappropriate assertions
- Poor error handling patterns
- Unclear error boundaries
- Ineffective defensive coding techniques

**Evaluation Questions:**
- Is input validation comprehensive and robust?
- Are assertions used appropriately to catch programming errors?
- Are error handling patterns consistent and clear?
- Are error boundaries clearly defined?
- Are defensive coding techniques used effectively?

### 5. Error Handling Consistency
**What to Look For:**
- Consistent error handling patterns throughout code
- Uniform error reporting mechanisms
- Standardized error recovery approaches
- Clear error handling conventions
- Predictable error behavior

**Common Problems:**
- Inconsistent error handling patterns
- Non-uniform error reporting mechanisms
- Standardized error recovery approaches
- Unclear error handling conventions
- Unpredictable error behavior

**Evaluation Questions:**
- 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?

## Error Handling Criticism Process

### Step 1: Error Checking 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?

### 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?

### Step 3: Error Recovery Evaluation
1. **Review Recovery Mechanisms**: Are error recovery mechanisms in place?
2. **Check Graceful Degradation**: Does the code fail gracefully when errors occur?
3. **Evaluate Resource Cleanup**: Is resource cleanup handled properly during errors?
4. **Assess Recovery Paths**: Are error recovery paths clear and effective?

### Step 4: Defensive Programming Analysis
1. **Check Input Validation**: Is input validation comprehensive and robust?
2. **Review Assertions**: Are assertions used appropriately to catch programming errors?
3. **Evaluate Error Patterns**: Are error handling patterns consistent and clear?
4. **Assess Error Boundaries**: Are error boundaries clearly defined?

## Error Handling Criticism Guidelines

### Focus on Error Handling Quality
**Good Criticism:**
- "This function doesn't check for potential errors in the file 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"

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

### 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"

**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"

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

## Error Handling Problem Categories

### Error Checking 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

### 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

### 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

### Defensive Programming Problems
- **Inadequate Validation**: Insufficient input validation
- **Missing Assertions**: Inappropriate or missing assertions
- **Poor Patterns**: Inconsistent error handling patterns
- **Unclear Boundaries**: Unclear error boundaries

## Error Handling Criticism Templates

### For Error Checking Issues
```
Error Checking Issue: [Specific error checking problem]
Problem: [How this violates good error checking principles]
Impact: [Reduced reliability, maintainability, or debugging capability]
Evidence: [Specific error checking examples and McConnell 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 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]
```

## Error Handling Criticism Best Practices

### Do's
- **Reference McConnell's Principles**: Always connect criticism to specific principles from Code Complete
- **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

### 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

## Error Handling Criticism Checklist

### Error Checking 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?

### 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?

### Error Recovery Assessment
- [ ] Are error recovery mechanisms in place?
- [ ] Does the code fail gracefully when errors occur?
- [ ] Is resource cleanup handled properly during errors?
- [ ] Are error recovery paths clear and effective?
- [ ] Are error handling strategies robust?

### Defensive Programming Assessment
- [ ] Is input validation comprehensive and robust?
- [ ] Are assertions used appropriately to catch programming errors?
- [ ] Are error handling patterns consistent and clear?
- [ ] Are error boundaries clearly defined?
- [ ] Are defensive coding techniques used effectively?

## Error Handling Evaluation Questions

### For Any Error Handling
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 Error Handling
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 Error Handling
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?**

## Code Complete 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

## Error Handling Quality Metrics

### Error Checking 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

### Error Recovery Metrics
- **Recovery Mechanisms**: Error recovery mechanisms should be in place
- **Graceful Degradation**: Code should fail gracefully when errors occur
- **Resource Cleanup**: Resource cleanup should be handled properly during errors
- **Recovery Paths**: Error recovery paths should be clear and effective

### Defensive Programming Metrics
- **Input Validation**: Input validation should be comprehensive and robust
- **Assertion Usage**: Assertions should be used appropriately
- **Error Patterns**: Error handling patterns should be consistent and clear
- **Error Boundaries**: Error boundaries should be clearly defined

## 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

### 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