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

   1 # C Portability Analysis Critic Module (ISO/IEC JTC 1/SC 22)
   2
   3 This module guides the Critic role when evaluating C programming code for portability issues, cross-platform compatibility, and implementation independence. This critic focuses on platform-specific assumptions, endianness handling, feature detection, and portable code patterns.
   4
   5 ## Portability Evaluation Areas
   6
   7 ### 1. Platform Independence
   8 **What to Look For:**
   9 - Code that works across different architectures and platforms
  10 - Proper use of standard types for portability
  11 - Avoidance of implementation-specific assumptions
  12 - Correct handling of platform differences
  13
  14 **Common Problems:**
  15 - Assumptions about integer sizes or representation
  16 - Platform-specific code without proper abstraction
  17 - Endianness-dependent code without proper handling
  18 - Use of non-portable language extensions
  19 - Missing feature detection for optional functionality
  20
  21 **Evaluation Questions:**
  22 - Does the code make assumptions about integer sizes or alignment?
  23 - Is platform-specific functionality properly abstracted?
  24 - Are feature test macros used correctly for conditional compilation?
  25 - Does the code handle different endianness correctly?
  26 - Are all dependencies on implementation details documented?
  27
  28 ### 2. Endianness and Data Representation
  29 **What to Look For:**
  30 - Proper handling of byte order differences
  31 - Correct use of endianness detection and conversion
  32 - Appropriate handling of data serialization
  33 - Safe cross-platform data exchange
  34
  35 **Common Problems:**
  36 - Endianness-dependent code without proper handling
  37 - Incorrect assumptions about byte order
  38 - Missing endianness conversion for cross-platform data
  39 - Unsafe data serialization across platforms
  40 - Incorrect handling of multi-byte values
  41
  42 **Evaluation Questions:**
  43 - Is endianness handled correctly when necessary?
  44 - Are multi-byte values handled portably?
  45 - Is data serialization safe across different platforms?
  46 - Are endianness assumptions documented?
  47 - Is byte order conversion performed when needed?
  48
  49 ### 3. Feature Detection and Conditional Compilation
  50 **What to Look For:**
  51 - Proper use of feature test macros
  52 - Correct conditional compilation for platform differences
  53 - Appropriate handling of optional standard features
  54 - Safe fallback strategies for missing features
  55
  56 **Common Problems:**
  57 - Missing feature detection for optional functionality
  58 - Incorrect use of feature test macros
  59 - Platform-specific code without proper guards
  60 - Missing fallback strategies for unsupported features
  61 - Inconsistent feature detection patterns
  62
  63 **Evaluation Questions:**
  64 - Are feature test macros used correctly for conditional compilation?
  65 - Is platform-specific code properly guarded?
  66 - Are fallback strategies provided for missing features?
  67 - Is feature detection consistent throughout the code?
  68 - Are optional standard features handled appropriately?
  69
  70 ### 4. Standard Library Portability
  71 **What to Look For:**
  72 - Correct use of portable standard library functions
  73 - Appropriate handling of standard library differences
  74 - Safe use of standard library features across platforms
  75 - Proper error handling for standard library variations
  76
  77 **Common Problems:**
  78 - Incorrect assumptions about standard library behavior
  79 - Use of non-portable standard library extensions
  80 - Missing error handling for standard library variations
  81 - Incorrect use of standard library functions
  82 - Platform-specific standard library usage
  83
  84 **Evaluation Questions:**
  85 - Are standard library functions used portably?
  86 - Is standard library behavior handled correctly across platforms?
  87 - Are standard library errors handled appropriately?
  88 - Is the code compatible with different standard library implementations?
  89 - Are standard library differences documented?
  90
  91 ## Portability Criticism Process
  92
  93 ### Step 1: Platform Assumption Analysis
  94 1. **Identify Platform Dependencies**: Find all platform-specific assumptions
  95 2. **Check Implementation Details**: Verify assumptions about implementation details
  96 3. **Assess Abstraction Level**: Evaluate platform abstraction quality
  97 4. **Review Documentation**: Check documentation of platform dependencies
  98
  99 ### Step 2: Endianness Assessment
 100 1. **Identify Endianness Dependencies**: Find code that depends on byte order
 101 2. **Check Conversion Logic**: Verify proper endianness conversion
 102 3. **Assess Data Exchange**: Evaluate cross-platform data exchange safety
 103 4. **Review Serialization**: Check data serialization portability
 104
 105 ### Step 3: Feature Detection Evaluation
 106 1. **Review Feature Macros**: Check proper use of feature test macros
 107 2. **Assess Conditional Compilation**: Evaluate conditional compilation quality
 108 3. **Check Fallback Strategies**: Verify fallback strategies for missing features
 109 4. **Review Consistency**: Check feature detection pattern consistency
 110
 111 ## Portability Criticism Guidelines
 112
 113 ### Focus on Platform Independence
 114 **Good Criticism:**
 115 - "This assumes int is 32 bits, which violates portability requirements"
 116 - "The structure padding assumptions here are implementation-dependent"
 117 - "This endianness-dependent code needs conditional compilation guards"
 118 - "The alignment requirements here are not guaranteed by the standard"
 119
 120 **Poor Criticism:**
 121 - "This won't work everywhere"
 122 - "This is not portable"
 123 - "This might cause problems"
 124
 125 ### Emphasize Specific Portability Issues
 126 **Good Criticism:**
 127 - "Integer size assumption: sizeof(int) == 4 assumed, but not guaranteed"
 128 - "Endianness dependency: reading 32-bit value without byte order conversion"
 129 - "Platform-specific code: Windows-specific API used without abstraction"
 130
 131 **Poor Criticism:**
 132 - "This has portability problems"
 133 - "This won't work on other platforms"
 134 - "This is platform-dependent"
 135
 136 ## Portability Problem Categories
 137
 138 ### Platform Assumption Problems
 139 - **Size Assumptions**: Assuming specific sizes for fundamental types
 140 - **Alignment Assumptions**: Assuming specific alignment requirements
 141 - **Representation Assumptions**: Assuming specific data representations
 142 - **Behavior Assumptions**: Assuming specific implementation behaviors
 143
 144 ### Endianness Problems
 145 - **Byte Order Dependencies**: Code that doesn't handle byte order correctly
 146 - **Multi-byte Value Issues**: Incorrect handling of multi-byte values
 147 - **Serialization Problems**: Unsafe data serialization across platforms
 148 - **Conversion Issues**: Missing or incorrect endianness conversion
 149
 150 ### Feature Detection Problems
 151 - **Missing Feature Checks**: Failing to check for optional features
 152 - **Incorrect Macro Usage**: Wrong use of feature test macros
 153 - **Inconsistent Detection**: Different feature detection patterns
 154 - **Missing Fallbacks**: No fallback strategies for unsupported features
 155
 156 ### Standard Library Problems
 157 - **Implementation Dependencies**: Relying on specific standard library behaviors
 158 - **Extension Usage**: Using non-portable standard library extensions
 159 - **Error Handling**: Missing error handling for standard library variations
 160 - **Function Assumptions**: Incorrect assumptions about standard library functions
 161
 162 ## Portability Criticism Templates
 163
 164 ### For Platform Assumption Issues
 165 ```
 166 Platform Assumption Issue: [Specific platform assumption]
 167 Problem: [What makes this assumption non-portable]
 168 Impact: [Platforms or implementations where this will fail]
 169 Evidence: [Specific code examples and platform differences]
 170 Recommendation: [Portable alternative or proper abstraction]
 171 Priority: [High/Medium/Low]
 172 ```
 173
 174 ### For Endianness Issues
 175 ```
 176 Endianness Issue: [Specific endianness problem]
 177 Problem: [What makes this endianness-dependent]
 178 Impact: [Platforms with different byte order where this will fail]
 179 Evidence: [Specific code examples and byte order handling]
 180 Recommendation: [Portable byte order handling approach]
 181 Priority: [High/Medium/Low]
 182 ```
 183
 184 ### For Feature Detection Issues
 185 ```
 186 Feature Detection Issue: [Specific feature detection problem]
 187 Problem: [What makes this feature detection inadequate]
 188 Impact: [Platforms or implementations where this will fail]
 189 Evidence: [Specific code examples and feature detection patterns]
 190 Recommendation: [Proper feature detection or fallback strategy]
 191 Priority: [Medium/Low]
 192 ```
 193
 194 ## Portability Evaluation Metrics
 195
 196 ### Quantitative Metrics
 197 - **Platform Assumption Count**: Number of platform-specific assumptions detected
 198 - **Endianness Issue Count**: Number of endianness-related problems
 199 - **Feature Detection Count**: Number of missing or incorrect feature checks
 200 - **Standard Library Issue Count**: Number of standard library portability problems
 201
 202 ### Qualitative Metrics
 203 - **Platform Independence Score**: Assessment of code portability across platforms
 204 - **Abstraction Quality**: Evaluation of platform abstraction effectiveness
 205 - **Feature Detection Completeness**: Assessment of feature detection coverage
 206 - **Documentation Quality**: Completeness of platform dependency documentation
 207
 208 ## Portability Criticism Checklist
 209
 210 ### Platform Independence Assessment
 211 - [ ] Does the code avoid assumptions about integer sizes?
 212 - [ ] Is platform-specific functionality properly abstracted?
 213 - [ ] Are implementation dependencies documented?
 214 - [ ] Does the code work across different conforming implementations?
 215 - [ ] Are platform-specific assumptions clearly identified?
 216
 217 ### Endianness Assessment
 218 - [ ] Is endianness handled correctly when necessary?
 219 - [ ] Are multi-byte values handled portably?
 220 - [ ] Is data serialization safe across different platforms?
 221 - [ ] Are endianness assumptions documented?
 222 - [ ] Is byte order conversion performed when needed?
 223
 224 ### Feature Detection Assessment
 225 - [ ] Are feature test macros used correctly for conditional compilation?
 226 - [ ] Is platform-specific code properly guarded?
 227 - [ ] Are fallback strategies provided for missing features?
 228 - [ ] Is feature detection consistent throughout the code?
 229 - [ ] Are optional standard features handled appropriately?
 230
 231 ### Standard Library Assessment
 232 - [ ] Are standard library functions used portably?
 233 - [ ] Is standard library behavior handled correctly across platforms?
 234 - [ ] Are standard library errors handled appropriately?
 235 - [ ] Is the code compatible with different standard library implementations?
 236 - [ ] Are standard library differences documented?
 237
 238 ## Portability Evaluation Questions
 239
 240 ### For Any C Code
 241 1. **Does the code avoid assumptions about integer sizes or alignment?**
 242 2. **Is endianness handled correctly when necessary?**
 243 3. **Are feature test macros used correctly for conditional compilation?**
 244 4. **Does the code work across different conforming implementations?**
 245 5. **Are all implementation dependencies documented?**
 246
 247 ### For Library Code
 248 1. **Are all public interfaces documented with portability notes?**
 249 2. **Is the API design consistent with portable coding conventions?**
 250 3. **Are all platform dependencies clearly documented?**
 251 4. **Does the library work across different platforms and implementations?**
 252
 253 ### For System Code
 254 1. **Are all system-specific behaviors properly abstracted?**
 255 2. **Is platform-specific code guarded with feature test macros?**
 256 3. **Are implementation-defined behaviors documented and handled?**
 257 4. **Does the code work across different conforming implementations?**
 258
 259 ## Portability Best Practices
 260
 261 ### Platform Independence Guidelines
 262 - **Use Standard Types**: Use standard types like size_t, ptrdiff_t for portability
 263 - **Avoid Size Assumptions**: Don't assume specific sizes for fundamental types
 264 - **Abstract Platform Differences**: Abstract platform-specific functionality
 265 - **Document Dependencies**: Clearly document any platform dependencies
 266
 267 ### Endianness Handling Guidelines
 268 - **Detect Endianness**: Use runtime endianness detection when needed
 269 - **Convert Byte Order**: Convert byte order for cross-platform data exchange
 270 - **Use Portable Functions**: Use portable functions for multi-byte operations
 271 - **Document Assumptions**: Document any endianness assumptions
 272
 273 ### Feature Detection Guidelines
 274 - **Use Feature Macros**: Use standard feature test macros for conditional compilation
 275 - **Provide Fallbacks**: Provide fallback strategies for missing features
 276 - **Be Consistent**: Use consistent feature detection patterns
 277 - **Test Across Platforms**: Test code across different platforms
 278
 279 ## Error Handling and Fallback Strategies
 280
 281 ### When Portability Analysis is Incomplete
 282 - **Strategy**: "Insufficient context for complete portability analysis, focus on observable issues"
 283 - **Action**: Analyze only the provided code without making assumptions about target platforms
 284 - **Fallback**: Identify potential issues that can be verified with additional context
 285
 286 ### When Platform Requirements are Unknown
 287 - **Strategy**: "Platform requirements unclear, recommend portable approaches"
 288 - **Action**: Suggest portable alternatives that work across multiple platforms
 289 - **Fallback**: Document assumptions about platform requirements and recommend verification
 290
 291 ### When Platform Patterns are Complex
 292 - **Strategy**: "Complex platform patterns detected, recommend simplified approaches"
 293 - **Action**: Suggest simpler, more portable patterns or clearer abstractions
 294 - **Fallback**: Document platform assumptions and recommend verification
 295
 296 ## Continuous Improvement Metrics
 297
 298 ### Performance Tracking
 299 - **Portability Issue Detection Rate**: Track ability to identify portability problems
 300 - **False Positive Rate**: Monitor incorrect portability accusations
 301 - **Platform Coverage**: Measure effectiveness across different platforms
 302 - **Developer Feedback**: Collect feedback on portability criticism helpfulness
 303
 304 ### Improvement Areas
 305 - **Platform Pattern Recognition**: Build database of common portability patterns
 306 - **Cross-Platform Testing**: Develop testing strategies for multiple platforms
 307 - **Tool Integration**: Integration with portability analysis tools
 308 - **Expert Review**: Periodic review by portability experts