begriffs open source - ai-review/blob - critic/c-error-handling.md

   1 # C Error Handling Critic Framework (ISO/IEC JTC 1/SC 22)
   2
   3 This framework guides the Critic role when evaluating C programming code for error handling completeness, robustness, and proper error propagation strategies from the perspective of ISO/IEC JTC 1/SC 22, the committee responsible for programming languages including the ISO/IEC 9899:1999 (C99) standard. This critic focuses on error checking, resource cleanup, error reporting, and graceful failure handling to ensure reliable, robust, and maintainable C code.
   4
   5 ## C Error Handling Evaluation Areas
   6
   7 ### 1. Function Return Value Checking
   8 **What to Look For:**
   9 - Consistent error checking for all fallible operations
  10 - Proper handling of function return values that indicate errors
  11 - Appropriate error propagation strategies
  12 - Clear error handling patterns throughout the codebase
  13
  14 **Common Problems:**
  15 - Ignoring return values from functions that can fail
  16 - Inconsistent error handling patterns
  17 - Missing error checking for critical operations
  18 - Improper error propagation to calling functions
  19 - Unclear error handling strategies
  20
  21 **Evaluation Questions:**
  22 - Are all function return values checked when they indicate errors?
  23 - Is error handling consistent throughout the codebase?
  24 - Are critical operation failures properly handled?
  25 - Is error information properly propagated to callers?
  26 - Are error handling patterns clearly documented?
  27
  28 ### 2. System Call and Library Function Error Handling
  29 **What to Look For:**
  30 - Proper use of errno for system call error reporting
  31 - Correct handling of system call failures
  32 - Appropriate error handling for standard library functions
  33 - Graceful handling of resource allocation failures
  34
  35 **Common Problems:**
  36 - Ignoring errno after system call failures
  37 - Not checking system call return values
  38 - Missing error handling for malloc/free failures
  39 - Incorrect interpretation of error codes
  40 - Inconsistent error handling for similar operations
  41
  42 **Evaluation Questions:**
  43 - Is errno used correctly for functions that set it?
  44 - Are all system call return values checked?
  45 - Are malloc/free failures handled appropriately?
  46 - Are error codes interpreted correctly?
  47 - Is error handling consistent for similar operations?
  48
  49 ### 3. Resource Cleanup on Error Paths
  50 **What to Look For:**
  51 - Proper resource cleanup when errors occur
  52 - Consistent cleanup patterns across error paths
  53 - Appropriate use of cleanup functions
  54 - Prevention of resource leaks during error conditions
  55
  56 **Common Problems:**
  57 - Resource leaks on error paths
  58 - Inconsistent cleanup patterns
  59 - Missing cleanup in error handling code
  60 - Improper resource ordering in cleanup
  61 - Incomplete cleanup when multiple resources are involved
  62
  63 **Evaluation Questions:**
  64 - Are resources cleaned up on all error paths?
  65 - Is cleanup performed in the correct order?
  66 - Are cleanup patterns consistent throughout the code?
  67 - Are all allocated resources properly released?
  68 - Is cleanup idempotent and safe?
  69
  70 ### 4. Error Reporting and Logging
  71 **What to Look For:**
  72 - Clear and actionable error messages
  73 - Appropriate error reporting mechanisms
  74 - Consistent error message formatting
  75 - Proper error logging and debugging information
  76
  77 **Common Problems:**
  78 - Unclear or unhelpful error messages
  79 - Inconsistent error reporting formats
  80 - Missing error context information
  81 - Inappropriate error message verbosity
  82 - Lack of debugging information for errors
  83
  84 **Evaluation Questions:**
  85 - Are error messages clear and actionable?
  86 - Is error reporting consistent throughout the code?
  87 - Is sufficient context provided with error messages?
  88 - Are error messages appropriate for the target audience?
  89 - Is debugging information available when needed?
  90
  91 ### 5. Error Propagation and Recovery
  92 **What to Look For:**
  93 - Proper propagation of error information to callers
  94 - Appropriate error recovery strategies
  95 - Graceful degradation when errors occur
  96 - Clear error state management
  97
  98 **Common Problems:**
  99 - Lost error information during propagation
 100 - Incorrect error propagation patterns
 101 - Silent failures without error indication
 102 - Poor error recovery strategies
 103 - Inconsistent error state management
 104
 105 **Evaluation Questions:**
 106 - Is error information properly propagated to callers?
 107 - Are error recovery strategies appropriate?
 108 - Is graceful degradation implemented when possible?
 109 - Is error state management clear and consistent?
 110 - Are silent failures avoided?
 111
 112 ## ISO/IEC Standards-Specific Error Handling Criticism Process
 113
 114 ### Step 1: Error Checking Analysis
 115 1. **Identify Fallible Operations**: Find all operations that can fail
 116 2. **Check Return Value Handling**: Verify all return values are checked
 117 3. **Assess Error Propagation**: Evaluate how errors are propagated
 118 4. **Review Error Patterns**: Check for consistency in error handling
 119
 120 ### Step 2: Resource Management Assessment
 121 1. **Track Resource Acquisition**: Identify all resource acquisitions
 122 2. **Verify Cleanup Paths**: Ensure cleanup occurs on all error paths
 123 3. **Check Cleanup Ordering**: Verify proper cleanup order
 124 4. **Assess Cleanup Completeness**: Ensure all resources are cleaned up
 125
 126 ### Step 3: Error Reporting Evaluation
 127 1. **Review Error Messages**: Assess clarity and usefulness of error messages
 128 2. **Check Error Context**: Verify sufficient context is provided
 129 3. **Evaluate Consistency**: Check for consistent error reporting patterns
 130 4. **Assess Debugging Support**: Verify debugging information availability
 131
 132 ### Step 4: Error Propagation Analysis
 133 1. **Check Error Propagation**: Are errors properly propagated to callers?
 134 2. **Evaluate Recovery**: Can the program recover gracefully from errors?
 135 3. **Assess Error State**: Is error state managed correctly?
 136 4. **Review Error Documentation**: Are error conditions clearly documented?
 137
 138 ## ISO/IEC Standards-Specific Error Handling Criticism Guidelines
 139
 140 ### Focus on Error Handling Completeness
 141 **Good Criticism:**
 142 - "Missing error check: malloc() return value not checked for NULL"
 143 - "Resource leak on error path: file handle not closed when function fails"
 144 - "Inconsistent error handling: similar operations handled differently"
 145 - "Poor error message: 'Error occurred' provides no actionable information"
 146
 147 **Poor Criticism:**
 148 - "Error handling seems incomplete"
 149 - "This might have error handling issues"
 150 - "Error handling could be better"
 151
 152 ### Emphasize Specific Error Issues
 153 **Good Criticism:**
 154 - "Function returns -1 on error but caller doesn't check return value"
 155 - "errno not checked after fopen() failure at line 23"
 156 - "Memory leak: malloc() at line 15, no cleanup on error path at line 28"
 157 - "Error propagation inconsistent: similar functions handle errors differently"
 158
 159 **Poor Criticism:**
 160 - "This has error handling problems"
 161 - "Error handling is inadequate"
 162 - "This will cause errors"
 163
 164 ### Consider Implementation Quality
 165 **Good Criticism:**
 166 - "The error checking here is incomplete - malloc can fail"
 167 - "This error path doesn't clean up resources properly"
 168 - "The error message here provides no actionable information"
 169 - "The error propagation here loses important context"
 170
 171 **Poor Criticism:**
 172 - "This has bugs"
 173 - "This is unreliable"
 174 - "This code is bad"
 175
 176 ## ISO/IEC Standards-Specific Error Handling Problem Categories
 177
 178 ### Error Checking Problems
 179 - **Unchecked Returns**: Ignoring function return values that indicate errors
 180 - **Inconsistent Checking**: Different error checking patterns for similar operations
 181 - **Missing Checks**: Failing to check return values from fallible operations
 182 - **Incorrect Interpretation**: Misinterpreting error codes or return values
 183
 184 ### Resource Management Problems
 185 - **Resource Leaks**: Failing to clean up resources on error paths
 186 - **Inconsistent Cleanup**: Different cleanup patterns in similar contexts
 187 - **Incomplete Cleanup**: Not cleaning up all resources when errors occur
 188 - **Cleanup Ordering**: Incorrect order of resource cleanup operations
 189
 190 ### Error Reporting Problems
 191 - **Unclear Messages**: Error messages that don't provide useful information
 192 - **Inconsistent Format**: Different error message formats throughout code
 193 - **Missing Context**: Error messages without sufficient context information
 194 - **Inappropriate Verbosity**: Error messages that are too verbose or too terse
 195
 196 ### Error Propagation Problems
 197 - **Lost Error Information**: Failing to propagate error information to callers
 198 - **Incorrect Propagation**: Propagating errors incorrectly or inconsistently
 199 - **Silent Failures**: Functions that fail silently without indicating errors
 200 - **Error Masking**: Hiding or masking important error information
 201
 202 ## ISO/IEC Standards-Specific Error Handling Criticism Templates
 203
 204 ### For Error Checking Issues
 205 ```
 206 Error Checking Issue: [Specific error checking problem]
 207 Standard Reference: [ISO/IEC 9899 section and paragraph]
 208 Problem: [What makes this error checking inadequate]
 209 Impact: [Potential crashes, silent failures, or incorrect behavior]
 210 Evidence: [Specific code examples showing missing checks]
 211 Priority: [Critical/High/Medium/Low]
 212 ```
 213
 214 ### For Resource Management Issues
 215 ```
 216 Resource Management Issue: [Specific resource management problem]
 217 Problem: [What causes the resource management issue]
 218 Impact: [Resource leaks, crashes, or system instability]
 219 Evidence: [Specific code paths showing resource acquisition and cleanup]
 220 Priority: [Critical/High/Medium/Low]
 221 ```
 222
 223 ### For Error Reporting Issues
 224 ```
 225 Error Reporting Issue: [Specific error reporting problem]
 226 Problem: [What makes this error reporting inadequate]
 227 Impact: [Poor debugging experience, user confusion, or maintenance issues]
 228 Evidence: [Specific error messages or reporting code]
 229 Priority: [High/Medium/Low]
 230 ```
 231
 232 ### For Error Propagation Issues
 233 ```
 234 Error Propagation Issue: [Specific error propagation problem]
 235 Problem: [What makes this error propagation inadequate]
 236 Impact: [Lost error information, silent failures, or incorrect error handling]
 237 Evidence: [Specific code examples showing propagation issues]
 238 Priority: [Critical/High/Medium/Low]
 239 ```
 240
 241 ## ISO/IEC Standards-Specific Error Handling Criticism Best Practices
 242
 243 ### Do's
 244 - **Cite Standard References**: Always reference specific sections of ISO/IEC 9899 when relevant
 245 - **Focus on Completeness**: Evaluate error handling completeness and consistency
 246 - **Consider All Error Paths**: Think about all possible error scenarios, not just happy paths
 247 - **Emphasize Robustness**: Prioritize robust error handling over convenience
 248 - **Document Error Handling**: Clearly identify error handling patterns and assumptions
 249
 250 ### Don'ts
 251 - **Assume Error-Free Code**: Don't assume code will never encounter errors
 252 - **Ignore Resource Management**: Don't overlook resource cleanup on error paths
 253 - **Accept Silent Failures**: Don't tolerate functions that fail silently
 254 - **Skip Error Checking**: Don't ignore error checking requirements
 255 - **Overlook Error Propagation**: Don't accept poor error propagation patterns
 256
 257 ## ISO/IEC Standards-Specific Error Handling Criticism Checklist
 258
 259 ### Error Checking Assessment
 260 - [ ] Are all function return values checked when they indicate errors?
 261 - [ ] Is error handling consistent throughout the codebase?
 262 - [ ] Are critical operation failures properly handled?
 263 - [ ] Is error information properly propagated to callers?
 264 - [ ] Are error handling patterns clearly documented?
 265
 266 ### Resource Management Assessment
 267 - [ ] Are resources cleaned up on all error paths?
 268 - [ ] Is cleanup performed in the correct order?
 269 - [ ] Are cleanup patterns consistent throughout the code?
 270 - [ ] Are all allocated resources properly released?
 271 - [ ] Is cleanup idempotent and safe?
 272
 273 ### Error Reporting Assessment
 274 - [ ] Are error messages clear and actionable?
 275 - [ ] Is error reporting consistent throughout the code?
 276 - [ ] Is sufficient context provided with error messages?
 277 - [ ] Are error messages appropriate for the target audience?
 278 - [ ] Is debugging information available when needed?
 279
 280 ### Error Propagation Assessment
 281 - [ ] Is error information properly propagated to callers?
 282 - [ ] Are error codes interpreted correctly?
 283 - [ ] Is error propagation consistent across similar operations?
 284 - [ ] Are silent failures avoided?
 285 - [ ] Is error masking prevented?
 286
 287 ## ISO/IEC Standards-Specific Error Handling Evaluation Questions
 288
 289 ### For Any C Code
 290 1. **Are all function return values checked when they indicate errors?**
 291 2. **Is errno used correctly for functions that set it?**
 292 3. **Are error conditions handled consistently throughout the codebase?**
 293 4. **Do error paths properly clean up allocated resources?**
 294 5. **Are error messages clear and actionable?**
 295 6. **Is error information properly propagated to callers?**
 296 7. **Are error recovery strategies appropriate?**
 297 8. **Is graceful degradation implemented when possible?**
 298 9. **Are silent failures avoided?**
 299 10. **Is error state management clear and consistent?**
 300
 301 ### For Library Code
 302 1. **Are all public interfaces documented with error conditions?**
 303 2. **Is error propagation clearly specified and implemented correctly?**
 304 3. **Are all parameters validated appropriately?**
 305 4. **Is the API design consistent with error handling conventions?**
 306 5. **Are all error conditions properly documented?**
 307
 308 ### For System Code
 309 1. **Are all system calls checked for errors?**
 310 2. **Is privilege escalation handled securely?**
 311 3. **Are buffer sizes validated before use?**
 312 4. **Is concurrency handled correctly?**
 313 5. **Are all security implications considered and addressed?**
 314
 315 ## C99 Standard Error Handling Principles Applied
 316
 317 ### "Provide a Robust Programming Language"
 318 - Write code that handles errors gracefully and consistently
 319 - Avoid silent failures and undefined error states
 320 - Use standard error handling patterns for maximum reliability
 321
 322 ### "Keep Error Handling Simple and Consistent"
 323 - Use consistent error handling patterns throughout the codebase
 324 - Avoid overly complex error handling when simpler alternatives exist
 325 - Prefer clear, predictable error handling over clever error recovery
 326
 327 ### "Provide Clear Error Information"
 328 - Ensure error messages provide actionable information
 329 - Propagate error context appropriately through the call stack
 330 - Document error conditions and recovery strategies clearly
 331
 332 ### "Make Error Handling Efficient"
 333 - Handle errors efficiently without unnecessary overhead
 334 - Use appropriate error handling mechanisms for the context
 335 - Avoid error handling that impacts performance unnecessarily
 336
 337 ### "Trust the Programmer to Handle Errors"
 338 - Provide tools for experienced programmers to handle errors appropriately
 339 - Allow low-level error handling when necessary
 340 - Don't prevent legitimate error handling strategies
 341
 342 ### "Don't Prevent the Programmer from Handling Errors Properly"
 343 - Enable comprehensive error handling and recovery
 344 - Provide mechanisms for all necessary error handling operations
 345 - Allow appropriate error handling overrides when explicitly requested
 346
 347 ## C Standard Library Error Handling Evaluation Criteria
 348
 349 ### Memory Management Functions
 350 - **malloc/free family**: Error checking, cleanup on failure, NULL pointer handling
 351 - **String functions**: Buffer overflow prevention, error propagation, cleanup
 352 - **Memory functions**: Error checking, resource cleanup, pointer validation
 353
 354 ### Input/Output Functions
 355 - **File operations**: Error checking, resource cleanup, mode validation
 356 - **Formatted I/O**: Error detection, buffer overflow prevention, cleanup
 357 - **Character I/O**: EOF handling, error conditions, resource management
 358
 359 ### String and Character Functions
 360 - **String manipulation**: Buffer bounds checking, error propagation, cleanup
 361 - **Character classification**: Error handling, locale considerations, validation
 362 - **String conversion**: Error detection, overflow handling, cleanup
 363
 364 ### Mathematical Functions
 365 - **Floating point**: Error handling, special values, precision considerations
 366 - **Integer arithmetic**: Overflow detection, error propagation, validation
 367 - **Random numbers**: Error handling, seeding validation, cleanup
 368
 369 ### Time and Date Functions
 370 - **Time representation**: Error handling, overflow detection, validation
 371 - **Formatting**: Error checking, buffer validation, cleanup
 372 - **Conversion**: Error detection, range validation, cleanup