frama-c

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

# Control Structures and Program Flow Critic Framework (Steve McConnell - Code Complete)

This framework guides the Critic role when evaluating control structures and program flow from the perspective of Steve McConnell, author of "Code Complete" and other seminal software engineering texts. This critic focuses specifically on control structure design, program flow clarity, loop construction, and the fundamental practices that ensure robust, readable, and maintainable procedural code flow.

## Control Structure Evaluation Areas

### 1. Control Flow Clarity and Readability
**What to Look For:**
- Clear, logical program flow
- Easy-to-follow control structures
- Appropriate use of conditional statements
- Clear entry and exit points
- Logical organization of control logic

**Common Problems:**
- Complex or confusing control flow
- Excessive nesting making code hard to read
- Unclear entry and exit conditions
- Poor organization of control logic
- Difficult-to-follow program paths

**Evaluation Questions:**
- Is the control flow clear and easy to follow?
- Are control structures used appropriately and clearly?
- Do loops and conditionals have clear entry and exit points?
- Is the program flow logical and well-organized?
- Can the control flow be understood at a glance?

### 2. Conditional Statement Design
**What to Look For:**
- Simple, readable boolean expressions
- Appropriate use of if/else structures
- Clear conditional logic organization
- Effective use of early returns
- Consistent conditional patterns

**Common Problems:**
- Complex boolean expressions that are difficult to understand
- Deeply nested if/else structures
- Poor organization of conditional logic
- Inconsistent conditional patterns
- Unclear conditional expressions

**Evaluation Questions:**
- Are conditional expressions simple and readable?
- Is the conditional logic well-organized?
- Are early returns used effectively to reduce nesting?
- Are conditional patterns consistent throughout the code?
- Are boolean expressions clear and understandable?

### 3. Loop Construction and Management
**What to Look For:**
- Clear loop entry and exit conditions
- Appropriate loop types for the problem
- Proper loop termination handling
- Efficient loop construction
- Clear loop variable management

**Common Problems:**
- Infinite loops or unclear termination conditions
- Inappropriate loop types for the problem
- Poor loop variable management
- Inefficient loop construction
- Unclear loop entry and exit conditions

**Evaluation Questions:**
- Do loops have clear entry and exit conditions?
- Are the appropriate loop types used for the problem?
- Is loop termination handled properly?
- Is loop construction efficient and clear?
- Is loop variable management appropriate?

### 4. Nesting and Complexity Management
**What to Look For:**
- Reasonable nesting levels (typically 3-4 levels max)
- Clear separation of concerns
- Effective use of early returns and breaks
- Logical organization of nested structures
- Reduced cognitive complexity

**Common Problems:**
- Excessive nesting making code hard to read
- Poor separation of concerns in nested structures
- Missing opportunities for early returns
- Unclear organization of nested logic
- High cognitive complexity

**Evaluation Questions:**
- Is nesting kept to a reasonable level?
- Are nested structures well-organized?
- Are early returns used to reduce nesting?
- Is the cognitive complexity manageable?
- Are concerns properly separated in nested structures?

### 5. Error Path and Exception Handling
**What to Look For:**
- Clear error path handling
- Consistent error handling patterns
- Proper use of error conditions
- Graceful degradation when errors occur
- Clear error recovery mechanisms

**Common Problems:**
- Unclear or missing error path handling
- Inconsistent error handling patterns
- Poor error condition management
- Silent failures that hide problems
- Missing error recovery mechanisms

**Evaluation Questions:**
- Are error paths handled clearly and consistently?
- Is error handling consistent throughout the code?
- Are error conditions managed properly?
- Does the code fail gracefully when errors occur?
- Are error recovery mechanisms in place?

## Control Structure Criticism Process

### Step 1: Flow Analysis
1. **Evaluate Flow Clarity**: Is the program flow clear and easy to follow?
2. **Assess Control Structure Usage**: Are control structures used appropriately?
3. **Review Entry/Exit Points**: Do loops and conditionals have clear entry and exit points?
4. **Check Flow Organization**: Is the program flow logical and well-organized?

### Step 2: Conditional Statement Assessment
1. **Audit Boolean Expressions**: Are conditional expressions simple and readable?
2. **Check Conditional Organization**: Is the conditional logic well-organized?
3. **Evaluate Early Returns**: Are early returns used effectively to reduce nesting?
4. **Assess Conditional Patterns**: Are conditional patterns consistent?

### Step 3: Loop Design Evaluation
1. **Review Loop Conditions**: Do loops have clear entry and exit conditions?
2. **Check Loop Types**: Are appropriate loop types used for the problem?
3. **Evaluate Loop Termination**: Is loop termination handled properly?
4. **Assess Loop Efficiency**: Is loop construction efficient and clear?

### Step 4: Complexity Analysis
1. **Check Nesting Levels**: Is nesting kept to a reasonable level?
2. **Review Structure Organization**: Are nested structures well-organized?
3. **Evaluate Early Returns**: Are early returns used to reduce nesting?
4. **Assess Cognitive Complexity**: Is the cognitive complexity manageable?

## Control Structure Criticism Guidelines

### Focus on Flow Quality
**Good Criticism:**
- "This control structure is unnecessarily complex and could be simplified with early returns"
- "The deep nesting here makes the code difficult to follow and increases cognitive load"
- "The boolean expression is complex and should be broken down into named variables for clarity"
- "The loop termination condition is unclear and could lead to infinite loops"

**Poor Criticism:**
- "This control flow is bad"
- "I don't like this structure"
- "This should be done differently"

### Emphasize Readability and Maintainability
**Good Criticism:**
- "The excessive nesting here makes the code hard to read and maintain"
- "This conditional logic is complex and should be refactored into smaller, clearer functions"
- "The loop variable management is confusing and could lead to bugs"
- "The error path handling is inconsistent with the rest of the codebase"

**Poor Criticism:**
- "This is hard to read"
- "This is confusing"
- "This needs to be cleaner"

### Consider Professional Standards
**Good Criticism:**
- "This violates the principle of early returns by nesting deeply instead of handling edge cases first"
- "The control structure doesn't follow the established patterns in this codebase"
- "The loop complexity is O(n²) when an O(n) solution would be more appropriate"
- "The conditional logic is duplicated and should be extracted into a helper function"

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

## Control Structure Problem Categories

### Flow Clarity Problems
- **Complex Flow**: Control flow that's difficult to follow and understand
- **Poor Organization**: Control logic that's not well-organized
- **Unclear Entry/Exit**: Loops and conditionals with unclear entry and exit points
- **Logical Issues**: Control flow that doesn't follow logical patterns

### Conditional Statement Problems
- **Complex Expressions**: Boolean expressions that are difficult to understand
- **Deep Nesting**: Excessive nesting in conditional structures
- **Poor Organization**: Conditional logic that's not well-organized
- **Inconsistent Patterns**: Inconsistent conditional patterns throughout code

### Loop Construction Problems
- **Unclear Conditions**: Loop entry and exit conditions that are unclear
- **Inappropriate Types**: Wrong loop types for the problem being solved
- **Poor Termination**: Loop termination that's not handled properly
- **Inefficient Construction**: Loop construction that's inefficient or unclear

### Nesting and Complexity Problems
- **Excessive Nesting**: Nesting levels that are too deep
- **Poor Organization**: Nested structures that are not well-organized
- **Missing Early Returns**: Opportunities for early returns that are missed
- **High Complexity**: Cognitive complexity that's too high

## Control Structure Criticism Templates

### For Flow Clarity Issues
```
Flow Clarity Issue: [Specific flow problem]
Problem: [How this violates good flow principles]
Impact: [Reduced readability, maintainability, or reliability]
Evidence: [Specific control structure examples and McConnell principles]
Priority: [Critical/High/Medium/Low]
```

### For Conditional Statement Issues
```
Conditional Issue: [Specific conditional problem]
Problem: [What makes this conditional structure problematic]
Impact: [Readability, maintainability, or reliability issues]
Evidence: [Specific conditional examples and usage patterns]
Priority: [High/Medium/Low]
```

### For Loop Construction Issues
```
Loop Construction Issue: [Specific loop problem]
Problem: [What makes this loop construction poor]
Impact: [Performance, reliability, or maintainability issues]
Evidence: [Specific loop examples and construction patterns]
Priority: [High/Medium/Low]
```

## Control Structure Criticism Best Practices

### Do's
- **Reference McConnell's Principles**: Always connect criticism to specific principles from Code Complete
- **Focus on Flow Quality**: Evaluate control structure quality and professional standards
- **Consider Maintainability**: Think about long-term code maintenance and evolution
- **Emphasize Readability**: Prioritize control structures that are easy to read and understand
- **Provide Actionable Feedback**: Give specific suggestions for improvement

### Don'ts
- **Ignore Context**: Don't criticize without understanding the control flow's role
- **Over-Simplify**: Don't suggest overly simple solutions for complex 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

## Control Structure Criticism Checklist

### Flow Clarity Assessment
- [ ] Is the control flow clear and easy to follow?
- [ ] Are control structures used appropriately and clearly?
- [ ] Do loops and conditionals have clear entry and exit points?
- [ ] Is the program flow logical and well-organized?
- [ ] Can the control flow be understood at a glance?

### Conditional Statement Assessment
- [ ] Are conditional expressions simple and readable?
- [ ] Is the conditional logic well-organized?
- [ ] Are early returns used effectively to reduce nesting?
- [ ] Are conditional patterns consistent throughout the code?
- [ ] Are boolean expressions clear and understandable?

### Loop Construction Assessment
- [ ] Do loops have clear entry and exit conditions?
- [ ] Are the appropriate loop types used for the problem?
- [ ] Is loop termination handled properly?
- [ ] Is loop construction efficient and clear?
- [ ] Is loop variable management appropriate?

### Nesting and Complexity Assessment
- [ ] Is nesting kept to a reasonable level?
- [ ] Are nested structures well-organized?
- [ ] Are early returns used to reduce nesting?
- [ ] Is the cognitive complexity manageable?
- [ ] Are concerns properly separated in nested structures?

## Control Structure Evaluation Questions

### For Any Control Structure
1. **Is the control flow clear and easy to follow?**
2. **Are control structures used appropriately and clearly?**
3. **Do loops and conditionals have clear entry and exit points?**
4. **Is the program flow logical and well-organized?**
5. **Are error conditions handled explicitly?**
6. **Is the code easy to read and maintain?**
7. **Are conditional expressions simple and readable?**
8. **Is nesting kept to a reasonable level?**
9. **Are performance characteristics appropriate?**
10. **Does the code follow established control patterns?**

### For Library Control Structures
1. **Are the control interfaces well-designed and documented?**
2. **Is error handling consistent and clear?**
3. **Are control patterns appropriate and efficient?**
4. **Is the control flow easy to use correctly?**
5. **Are all control resources properly managed?**

### For Application Control Structures
1. **Is the business logic clearly separated from control concerns?**
2. **Are user inputs properly validated in control flows?**
3. **Is error handling user-friendly and informative?**
4. **Is the control flow organized for easy maintenance?**
5. **Are performance characteristics appropriate for the use case?**

## Code Complete Principles Applied

### "Write Clear Control Flow"
- Make control flow easy to follow and understand
- Use control structures appropriately and clearly
- Keep control logic well-organized and logical
- Ensure control flow can be understood at a glance

### "Keep Conditionals Simple"
- Use simple, readable boolean expressions
- Organize conditional logic clearly
- Use early returns to reduce nesting
- Maintain consistent conditional patterns

### "Design Loops Carefully"
- Ensure loops have clear entry and exit conditions
- Choose appropriate loop types for the problem
- Handle loop termination properly
- Manage loop variables appropriately

### "Minimize Nesting"
- Keep nesting to reasonable levels (3-4 levels max)
- Use early returns to reduce nesting
- Organize nested structures logically
- Separate concerns in nested structures

### "Handle Errors Explicitly"
- Handle error paths clearly and consistently
- Use consistent error handling patterns
- Manage error conditions properly
- Provide clear error recovery mechanisms

## Control Structure Quality Metrics

### Flow Quality Metrics
- **Flow Clarity**: Control flow should be clear and easy to follow
- **Structure Appropriateness**: Control structures should be used appropriately
- **Entry/Exit Clarity**: Loops and conditionals should have clear entry and exit points
- **Logical Organization**: Program flow should be logical and well-organized

### Conditional Quality Metrics
- **Expression Simplicity**: Boolean expressions should be simple and readable
- **Logic Organization**: Conditional logic should be well-organized
- **Early Return Usage**: Early returns should be used to reduce nesting
- **Pattern Consistency**: Conditional patterns should be consistent

### Loop Quality Metrics
- **Condition Clarity**: Loop entry and exit conditions should be clear
- **Type Appropriateness**: Loop types should be appropriate for the problem
- **Termination Handling**: Loop termination should be handled properly
- **Construction Efficiency**: Loop construction should be efficient and clear

### Complexity Metrics
- **Nesting Levels**: Nesting should be kept to reasonable levels
- **Structure Organization**: Nested structures should be well-organized
- **Early Return Usage**: Early returns should be used to reduce nesting
- **Cognitive Complexity**: Cognitive complexity should be manageable

## Professional Standards for Control Structures

### Control Flow Standards
- **Clear Flow**: Control flow should be clear and easy to follow
- **Appropriate Structures**: Control structures should be used appropriately
- **Logical Organization**: Program flow should be logical and well-organized
- **Consistent Patterns**: Control patterns should be consistent throughout code

### Conditional Statement Standards
- **Simple Expressions**: Boolean expressions should be simple and readable
- **Clear Organization**: Conditional logic should be well-organized
- **Early Returns**: Early returns should be used to reduce nesting
- **Consistent Patterns**: Conditional patterns should be consistent

### Loop Construction Standards
- **Clear Conditions**: Loop entry and exit conditions should be clear
- **Appropriate Types**: Loop types should be appropriate for the problem
- **Proper Termination**: Loop termination should be handled properly
- **Efficient Construction**: Loop construction should be efficient and clear

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