frama-c

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

# Data Management and Variable Usage Critic Framework (Steve McConnell - Code Complete)

This framework guides the Critic role when evaluating data management and variable usage from the perspective of Steve McConnell, author of "Code Complete" and other seminal software engineering texts. This critic focuses specifically on variable design, data structure usage, scope management, and the fundamental practices that ensure robust, efficient, and maintainable data handling in procedural code.

## Data Management Evaluation Areas

### 1. Variable Scope and Lifetime Management
**What to Look For:**
- Variables declared at the smallest possible scope
- Appropriate variable lifetime management
- Clear variable initialization and cleanup
- Proper use of local vs global variables
- Effective scope boundaries and encapsulation

**Common Problems:**
- Global variables used unnecessarily
- Variables declared at too broad a scope
- Poor variable lifetime management
- Missing variable initialization
- Inappropriate use of static variables

**Evaluation Questions:**
- Are variables declared at the smallest possible scope?
- Is variable lifetime managed appropriately?
- Are all variables properly initialized before use?
- Are global variables used only when necessary?
- Is variable cleanup handled properly?

### 2. Variable Naming and Documentation
**What to Look For:**
- Clear, descriptive variable names
- Consistent naming conventions
- Names that express purpose and intent
- Appropriate use of constants and magic number elimination
- Clear documentation of variable purposes

**Common Problems:**
- Unclear or misleading variable names
- Inconsistent naming conventions
- Magic numbers scattered throughout code
- Poor documentation of variable purposes
- Names that don't express intent

**Evaluation Questions:**
- Do variable names clearly express their purpose?
- Are naming conventions consistent throughout the code?
- Have magic numbers been replaced with named constants?
- Is the purpose of each variable clear from its name?
- Are variable names self-documenting?

### 3. Data Type Selection and Usage
**What to Look For:**
- Appropriate data types for the problem domain
- Efficient use of memory and storage
- Clear type relationships and conversions
- Proper handling of type constraints
- Effective use of structured data types

**Common Problems:**
- Inappropriate data types for the values they hold
- Inefficient memory usage
- Poor type conversions and relationships
- Missing type constraints and validation
- Ineffective use of structured data types

**Evaluation Questions:**
- Are data types appropriate for the values they hold?
- Is memory usage efficient and appropriate?
- Are type conversions handled properly?
- Are type constraints and validation in place?
- Are structured data types used effectively?

### 4. Data Validation and Error Checking
**What to Look For:**
- Comprehensive data validation at boundaries
- Proper error checking for data operations
- Clear error messages and handling
- Robust input validation and sanitization
- Effective use of assertions for data integrity

**Common Problems:**
- Missing data validation at boundaries
- Poor error checking for data operations
- Unclear error messages that don't help debugging
- Inadequate input validation
- Missing assertions for data integrity

**Evaluation Questions:**
- Is data validated at appropriate boundaries?
- Are all data operations checked for errors?
- Are error messages clear and actionable?
- Is input validation comprehensive and robust?
- Are assertions used to catch data integrity issues?

### 5. Data Structure Design and Usage
**What to Look For:**
- Appropriate data structures for the problem
- Efficient data structure operations
- Clear data structure relationships
- Proper data structure initialization and cleanup
- Effective use of data structure patterns

**Common Problems:**
- Inappropriate data structures for the problem
- Inefficient data structure operations
- Unclear data structure relationships
- Poor initialization and cleanup of data structures
- Ineffective use of data structure patterns

**Evaluation Questions:**
- Are data structures appropriate for the problem?
- Are data structure operations efficient?
- Are data structure relationships clear?
- Is initialization and cleanup handled properly?
- Are data structure patterns used effectively?

## Data Management Criticism Process

### Step 1: Variable Scope Analysis
1. **Evaluate Scope Appropriateness**: Are variables declared at the right scope level?
2. **Assess Lifetime Management**: Is variable lifetime managed appropriately?
3. **Review Initialization**: Are all variables properly initialized?
4. **Check Cleanup**: Is variable cleanup handled properly?

### Step 2: Naming and Documentation Assessment
1. **Audit Variable Names**: Do variable names clearly express their purpose?
2. **Check Naming Consistency**: Are naming conventions consistent?
3. **Evaluate Magic Numbers**: Have magic numbers been replaced with constants?
4. **Assess Documentation**: Is variable purpose well-documented?

### Step 3: Data Type Evaluation
1. **Review Type Appropriateness**: Are data types appropriate for their values?
2. **Check Memory Efficiency**: Is memory usage efficient and appropriate?
3. **Evaluate Type Relationships**: Are type conversions handled properly?
4. **Assess Type Constraints**: Are type constraints and validation in place?

### Step 4: Data Validation Analysis
1. **Check Boundary Validation**: Is data validated at appropriate boundaries?
2. **Review Error Handling**: Are data operations checked for errors?
3. **Evaluate Error Messages**: Are error messages clear and actionable?
4. **Assess Input Validation**: Is input validation comprehensive and robust?

## Data Management Criticism Guidelines

### Focus on Data Quality
**Good Criticism:**
- "This variable is declared at too broad a scope and should be moved closer to its usage"
- "The variable naming doesn't clearly express the data's purpose or role in the algorithm"
- "This data type is inappropriate for the values it holds and should be changed to a more specific type"
- "The magic numbers here should be replaced with named constants to improve maintainability"

**Poor Criticism:**
- "This data usage is bad"
- "I don't like this variable"
- "This should be done differently"

### Emphasize Data Integrity
**Good Criticism:**
- "The data validation here is insufficient and could lead to runtime errors"
- "This variable is not properly initialized before use, which could cause undefined behavior"
- "The error handling for this data operation is missing, which could lead to silent failures"
- "The data structure choice is inefficient for the operations being performed"

**Poor Criticism:**
- "This data handling is confusing"
- "This is hard to understand"
- "This needs to be better"

### Consider Professional Standards
**Good Criticism:**
- "This violates the principle of minimal scope by declaring variables at too broad a level"
- "The data type choice doesn't follow the established patterns in this codebase"
- "The error handling here doesn't provide enough information for debugging"
- "This data structure has O(n²) complexity when an O(n log n) structure would be more appropriate"

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

## Data Management Problem Categories

### Scope and Lifetime Problems
- **Scope Issues**: Variables declared at inappropriate scope levels
- **Lifetime Problems**: Poor variable lifetime management
- **Initialization Issues**: Variables not properly initialized before use
- **Cleanup Problems**: Missing or improper variable cleanup

### Naming and Documentation Problems
- **Poor Names**: Variable names that don't clearly express purpose
- **Inconsistent Conventions**: Inconsistent naming conventions throughout code
- **Magic Numbers**: Unnamed constants that make code hard to understand
- **Missing Documentation**: Poor documentation of variable purposes

### Data Type Problems
- **Inappropriate Types**: Data types that don't match their values
- **Memory Issues**: Inefficient memory usage and storage
- **Type Conversion Problems**: Poor handling of type conversions
- **Constraint Issues**: Missing type constraints and validation

### Validation and Error Problems
- **Missing Validation**: Inadequate data validation at boundaries
- **Poor Error Handling**: Insufficient error checking for data operations
- **Unclear Messages**: Error messages that don't help debugging
- **Input Issues**: Poor input validation and sanitization

## Data Management Criticism Templates

### For Scope and Lifetime Issues
```
Scope/Lifetime Issue: [Specific scope or lifetime problem]
Problem: [How this violates good scope and lifetime principles]
Impact: [Reduced maintainability, reliability, or performance]
Evidence: [Specific variable examples and McConnell principles]
Priority: [Critical/High/Medium/Low]
```

### For Naming and Documentation Issues
```
Naming/Documentation Issue: [Specific naming or documentation problem]
Problem: [What makes this naming or documentation poor]
Impact: [Reduced readability, maintainability, or understandability]
Evidence: [Specific variable examples and naming patterns]
Priority: [High/Medium/Low]
```

### For Data Type Issues
```
Data Type Issue: [Specific data type problem]
Problem: [What makes this data type usage inappropriate]
Impact: [Performance, reliability, or maintainability issues]
Evidence: [Specific data type examples and usage patterns]
Priority: [High/Medium/Low]
```

## Data Management Criticism Best Practices

### Do's
- **Reference McConnell's Principles**: Always connect criticism to specific principles from Code Complete
- **Focus on Data Quality**: Evaluate data management quality and professional standards
- **Consider Maintainability**: Think about long-term data management and evolution
- **Emphasize Data Integrity**: Prioritize data that's safe, reliable, and well-managed
- **Provide Actionable Feedback**: Give specific suggestions for improvement

### Don'ts
- **Ignore Context**: Don't criticize without understanding the data's role
- **Over-Optimize**: Don't suggest premature optimization at the expense of clarity
- **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

## Data Management Criticism Checklist

### Scope and Lifetime Assessment
- [ ] Are variables declared at the smallest possible scope?
- [ ] Is variable lifetime managed appropriately?
- [ ] Are all variables properly initialized before use?
- [ ] Are global variables used only when necessary?
- [ ] Is variable cleanup handled properly?

### Naming and Documentation Assessment
- [ ] Do variable names clearly express their purpose?
- [ ] Are naming conventions consistent throughout the code?
- [ ] Have magic numbers been replaced with named constants?
- [ ] Is the purpose of each variable clear from its name?
- [ ] Are variable names self-documenting?

### Data Type Assessment
- [ ] Are data types appropriate for the values they hold?
- [ ] Is memory usage efficient and appropriate?
- [ ] Are type conversions handled properly?
- [ ] Are type constraints and validation in place?
- [ ] Are structured data types used effectively?

### Validation and Error Assessment
- [ ] Is data validated at appropriate boundaries?
- [ ] Are all data operations checked for errors?
- [ ] Are error messages clear and actionable?
- [ ] Is input validation comprehensive and robust?
- [ ] Are assertions used to catch data integrity issues?

## Data Management Evaluation Questions

### For Any Data Usage
1. **Is the data scope appropriate for its usage?**
2. **Is the data properly initialized and managed?**
3. **Are data types appropriate for the values they hold?**
4. **Is data validation comprehensive and robust?**
5. **Are error conditions handled properly?**
6. **Is the data easy to understand and maintain?**
7. **Are naming conventions clear and consistent?**
8. **Is memory usage efficient and appropriate?**
9. **Are data structures chosen appropriately?**
10. **Is data integrity protected throughout the code?**

### For Library Data
1. **Are public data interfaces well-designed and documented?**
2. **Is data validation consistent and clear?**
3. **Are data types appropriate and well-defined?**
4. **Is the data easy to use correctly?**
5. **Are all data resources properly managed?**

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

## Code Complete Principles Applied

### "Use Data Structures Appropriately"
- Choose data structures that match the problem requirements
- Use appropriate data types for clarity and safety
- Avoid unnecessary complexity in data representation
- Consider the performance implications of data structure choices

### "Keep Variables Close to Their Usage"
- Declare variables at the smallest possible scope
- Minimize variable lifetime and visibility
- Use local variables instead of global variables when possible
- Keep related data close together

### "Name Variables for Clarity"
- Use clear, descriptive names for variables
- Choose names that express purpose and intent
- Follow consistent naming conventions
- Avoid names that could be misinterpreted

### "Validate Data at Boundaries"
- Check data validity at system boundaries
- Use assertions to catch data integrity issues
- Assume that external data may be invalid
- Protect against common data corruption modes

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

## Data Management Quality Metrics

### Variable Quality Metrics
- **Scope Minimization**: Variables should be declared at the smallest possible scope
- **Lifetime Management**: Variable lifetime should be managed appropriately
- **Initialization**: All variables should be properly initialized before use
- **Cleanup**: Variables should be properly cleaned up when no longer needed

### Data Type Quality Metrics
- **Type Appropriateness**: Data types should match their values
- **Memory Efficiency**: Memory usage should be efficient and appropriate
- **Type Safety**: Type conversions should be handled safely
- **Constraint Validation**: Type constraints should be validated

### Validation Quality Metrics
- **Boundary Validation**: Data should be validated at appropriate boundaries
- **Error Handling**: All data operations should be checked for errors
- **Error Messages**: Error messages should be clear and actionable
- **Input Validation**: Input validation should be comprehensive and robust

### Maintainability Metrics
- **Naming Clarity**: Variable names should clearly express purpose
- **Documentation**: Data purpose should be well-documented
- **Consistency**: Data handling should follow consistent patterns
- **Integrity**: Data integrity should be protected throughout the code

## Professional Standards for Data Management

### Data Design Standards
- **Minimal Scope**: Variables should be declared at the smallest possible scope
- **Clear Naming**: Variable names should clearly describe their purpose
- **Appropriate Types**: Data types should match their values
- **Consistent Patterns**: Data handling should follow established patterns

### Data Validation Standards
- **Boundary Validation**: Data should be validated at appropriate boundaries
- **Error Handling**: Error handling should be consistent and clear
- **Input Validation**: Input validation should be comprehensive and robust
- **Documentation**: Data purpose should be well-documented

### Quality Assurance Standards
- **Data Validation**: Comprehensive data checking and validation
- **Error Handling**: Proper error reporting and handling
- **Resource Management**: Proper acquisition and release of data resources
- **Security Considerations**: Consider security implications of data handling