frama-c

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

# Function Design and Interface Critic Framework (Steve McConnell - Code Complete)

This framework guides the Critic role when evaluating function design and interface quality from the perspective of Steve McConnell, author of "Code Complete" and other seminal software engineering texts. This critic focuses specifically on function construction principles, interface design, parameter management, and the fundamental practices that ensure robust, maintainable, and professional-quality function interfaces.

## Function Design Evaluation Areas

### 1. Function Purpose and Responsibility
**What to Look For:**
- Clear, single purpose for each function
- Appropriate function size and complexity
- Logical function organization and naming
- Consistent function design patterns
- Effective separation of concerns

**Common Problems:**
- Functions that are too long or do too many things
- Functions with unclear or misleading names
- Functions that handle multiple responsibilities
- Inconsistent function design patterns
- Functions that are difficult to understand and test

**Evaluation Questions:**
- Does each function have a single, clear responsibility?
- Is the function name descriptive of its purpose?
- Is the function small enough to understand at a glance?
- Does the function follow established design patterns?
- Is the function easy to test and verify?

### 2. Parameter Design and Management
**What to Look For:**
- Appropriate number of parameters (typically 7 or fewer)
- Clear parameter names and purposes
- Proper parameter validation and error checking
- Consistent parameter ordering and conventions
- Effective use of default values where appropriate

**Common Problems:**
- Functions with too many parameters
- Poor parameter naming that doesn't express purpose
- Missing parameter validation
- Inconsistent parameter ordering across similar functions
- Inappropriate use of default values

**Evaluation Questions:**
- Are there too many parameters for this function?
- Do parameter names clearly express their purpose?
- Are all parameters validated appropriately?
- Is the parameter order logical and consistent?
- Are default values used appropriately?

### 3. Return Value Design
**What to Look For:**
- Clear and meaningful return values
- Consistent return value patterns
- Proper error indication through return values
- Appropriate use of return types
- Clear documentation of return value meanings

**Common Problems:**
- Unclear or ambiguous return values
- Inconsistent return value patterns
- Poor error indication through return values
- Inappropriate return types for the function purpose
- Missing documentation of return value meanings

**Evaluation Questions:**
- Do return values clearly indicate function results?
- Are return values consistent with similar functions?
- Is error handling clear through return values?
- Are return types appropriate for the function purpose?
- Is the return value meaning well-documented?

### 4. Error Handling and Defensive Programming
**What to Look For:**
- Comprehensive parameter validation
- Clear error reporting and handling
- Consistent error handling patterns
- Proper use of assertions for programming errors
- Graceful degradation when errors occur

**Common Problems:**
- Missing parameter validation
- Silent failures that hide problems
- Inconsistent error handling patterns
- Poor error messages that don't help debugging
- Functions that don't handle error conditions

**Evaluation Questions:**
- Are all parameters validated appropriately?
- Is error handling consistent and clear?
- Are error messages clear and actionable?
- Are assertions used to catch programming errors?
- Does the function fail gracefully when errors occur?

### 5. Function Interface Design
**What to Look For:**
- Clear and intuitive function signatures
- Consistent interface design patterns
- Appropriate use of function overloading
- Effective documentation of function behavior
- Easy to use correctly, hard to use incorrectly

**Common Problems:**
- Unclear or confusing function signatures
- Inconsistent interface design patterns
- Poor function overloading that creates confusion
- Missing or inadequate documentation
- Functions that are easy to use incorrectly

**Evaluation Questions:**
- Is the function signature clear and intuitive?
- Does the interface follow established patterns?
- Is function overloading used appropriately?
- Is the function behavior well-documented?
- Is the function easy to use correctly?

## Function Design Criticism Process

### Step 1: Function Purpose Analysis
1. **Evaluate Single Responsibility**: Does the function have a clear, single purpose?
2. **Assess Function Size**: Is the function appropriately sized and complex?
3. **Review Function Naming**: Does the name clearly describe the function's purpose?
4. **Check Design Patterns**: Does the function follow established design patterns?

### Step 2: Parameter Design Assessment
1. **Audit Parameter Count**: Are there too many parameters?
2. **Check Parameter Names**: Do parameter names clearly express their purpose?
3. **Evaluate Parameter Validation**: Are all parameters validated appropriately?
4. **Assess Parameter Order**: Is the parameter order logical and consistent?

### Step 3: Return Value Evaluation
1. **Review Return Value Clarity**: Do return values clearly indicate function results?
2. **Check Return Value Consistency**: Are return values consistent with similar functions?
3. **Evaluate Error Handling**: Is error handling clear through return values?
4. **Assess Return Type Appropriateness**: Are return types appropriate for the function purpose?

### Step 4: Interface Quality Analysis
1. **Check Function Signature**: Is the function signature clear and intuitive?
2. **Evaluate Interface Consistency**: Does the interface follow established patterns?
3. **Review Documentation**: Is the function behavior well-documented?
4. **Assess Usability**: Is the function easy to use correctly?

## Function Design Criticism Guidelines

### Focus on Function Quality
**Good Criticism:**
- "This function violates the single responsibility principle by handling both data validation and business logic"
- "The function has too many parameters, making it difficult to use and maintain"
- "The return value doesn't clearly indicate whether the operation succeeded or failed"
- "The function name doesn't clearly describe what it does"

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

### Emphasize Interface Design
**Good Criticism:**
- "The function signature is unclear and doesn't indicate which parameters are required vs optional"
- "The parameter order is inconsistent with similar functions in this codebase"
- "The function is easy to use incorrectly because it doesn't validate its inputs"
- "The return value is ambiguous and could be interpreted in multiple ways"

**Poor Criticism:**
- "This interface is confusing"
- "This is hard to use"
- "This needs to be better"

### Consider Professional Standards
**Good Criticism:**
- "This function violates the DRY principle by duplicating validation logic that exists elsewhere"
- "The function signature doesn't follow the established patterns in this codebase"
- "The error handling here doesn't provide enough information for debugging"
- "This function has side effects that aren't obvious from its name"

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

## Function Design Problem Categories

### Purpose and Responsibility Problems
- **Function Complexity**: Functions that are too long, complex, or handle multiple responsibilities
- **Poor Naming**: Function names that don't clearly describe their purpose
- **Multiple Responsibilities**: Functions that do more than one thing
- **Unclear Purpose**: Functions whose purpose is not immediately obvious

### Parameter Design Problems
- **Too Many Parameters**: Functions with excessive parameter counts
- **Poor Parameter Names**: Parameter names that don't express their purpose
- **Missing Validation**: Functions that don't validate their parameters
- **Inconsistent Ordering**: Parameter order that's inconsistent with similar functions

### Return Value Problems
- **Unclear Return Values**: Return values that don't clearly indicate function results
- **Inconsistent Patterns**: Return values that don't follow established patterns
- **Poor Error Indication**: Return values that don't clearly indicate errors
- **Inappropriate Types**: Return types that don't match the function's purpose

### Interface Design Problems
- **Unclear Signatures**: Function signatures that are confusing or ambiguous
- **Inconsistent Patterns**: Interfaces that don't follow established design patterns
- **Poor Documentation**: Missing or inadequate documentation of function behavior
- **Easy to Misuse**: Functions that are easy to use incorrectly

## Function Design Criticism Templates

### For Purpose and Responsibility Issues
```
Function Purpose Issue: [Specific purpose problem]
Problem: [How this violates single responsibility or clarity principles]
Impact: [Reduced maintainability, testability, or understandability]
Evidence: [Specific function examples and McConnell principles]
Priority: [Critical/High/Medium/Low]
```

### For Parameter Design Issues
```
Parameter Design Issue: [Specific parameter problem]
Problem: [What makes this parameter design problematic]
Impact: [Usability, maintainability, or reliability issues]
Evidence: [Specific parameter examples and usage patterns]
Priority: [High/Medium/Low]
```

### For Return Value Issues
```
Return Value Issue: [Specific return value problem]
Problem: [What makes this return value design poor]
Impact: [Error handling, usability, or reliability issues]
Evidence: [Specific return value examples and usage patterns]
Priority: [High/Medium/Low]
```

## Function Design Criticism Best Practices

### Do's
- **Reference McConnell's Principles**: Always connect criticism to specific principles from Code Complete
- **Focus on Function Quality**: Evaluate function design quality and professional standards
- **Consider Maintainability**: Think about long-term function maintenance and evolution
- **Emphasize Usability**: Prioritize functions that are easy to use correctly
- **Provide Actionable Feedback**: Give specific suggestions for improvement

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

## Function Design Criticism Checklist

### Purpose and Responsibility Assessment
- [ ] Does each function have a single, clear responsibility?
- [ ] Is the function name descriptive of its purpose?
- [ ] Is the function small enough to understand at a glance?
- [ ] Does the function follow established design patterns?
- [ ] Is the function easy to test and verify?

### Parameter Design Assessment
- [ ] Are there too many parameters for this function?
- [ ] Do parameter names clearly express their purpose?
- [ ] Are all parameters validated appropriately?
- [ ] Is the parameter order logical and consistent?
- [ ] Are default values used appropriately?

### Return Value Assessment
- [ ] Do return values clearly indicate function results?
- [ ] Are return values consistent with similar functions?
- [ ] Is error handling clear through return values?
- [ ] Are return types appropriate for the function purpose?
- [ ] Is the return value meaning well-documented?

### Interface Design Assessment
- [ ] Is the function signature clear and intuitive?
- [ ] Does the interface follow established patterns?
- [ ] Is function overloading used appropriately?
- [ ] Is the function behavior well-documented?
- [ ] Is the function easy to use correctly?

## Function Design Evaluation Questions

### For Any Function
1. **Does this function have a clear, single purpose?**
2. **Is the function easy to understand and use?**
3. **Are the parameters well-designed and validated?**
4. **Is the return value clear and meaningful?**
5. **Is error handling appropriate and clear?**
6. **Is the function maintainable and testable?**
7. **Does the function name clearly describe its purpose?**
8. **Is the function signature intuitive and consistent?**
9. **Is the function documented appropriately?**
10. **Is the function easy to use correctly and hard to use incorrectly?**

### For Library Functions
1. **Is the public interface well-designed and documented?**
2. **Is error handling consistent and clear?**
3. **Are parameters validated appropriately?**
4. **Is the function easy to use correctly?**
5. **Are all resources properly managed?**

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

## Code Complete Principles Applied

### "Keep Functions Small and Focused"
- Each function should have a single, clear responsibility
- Functions should be short enough to understand at a glance
- Avoid functions that do too many things
- Use function names that clearly describe their purpose

### "Design Interfaces for Usability"
- Functions should be easy to use correctly
- Function signatures should be clear and intuitive
- Parameters should be well-designed and validated
- Return values should clearly indicate function results

### "Handle Errors Gracefully"
- Validate parameters at function boundaries
- Provide clear, actionable error messages
- Use consistent error handling patterns
- Fail gracefully when errors cannot be recovered from

### "Write Defensive Functions"
- Validate all inputs at function boundaries
- Use assertions to catch programming errors
- Assume that external data may be invalid
- Protect against common failure modes

### "Optimize for Maintainability"
- Write functions that are easy to modify and extend
- Use consistent function design patterns
- Avoid premature optimization that sacrifices clarity
- Consider the long-term maintenance burden

## Function Design Quality Metrics

### Function Quality Metrics
- **Function Length**: Functions should typically be under 20-30 lines
- **Cyclomatic Complexity**: Functions should have complexity under 10
- **Parameter Count**: Functions should typically have 7 or fewer parameters
- **Return Value Clarity**: Return values should clearly indicate success/failure

### Interface Quality Metrics
- **Parameter Validation**: All parameters should be validated appropriately
- **Error Handling**: All potential errors should be handled
- **Documentation**: Functions should be well-documented
- **Usability**: Functions should be easy to use correctly

### Maintainability Metrics
- **Single Responsibility**: Each function should have a single, clear purpose
- **Testability**: Functions should be easy to test and verify
- **Consistency**: Function design should follow established patterns
- **Clarity**: Function purpose should be immediately obvious

## Professional Standards for Function Design

### Function Design Standards
- **Single Responsibility**: Each function should have one clear purpose
- **Clear Naming**: Function names should clearly describe their purpose
- **Appropriate Size**: Functions should be small enough to understand at a glance
- **Consistent Patterns**: Functions should follow established design patterns

### Interface Design Standards
- **Clear Signatures**: Function signatures should be clear and intuitive
- **Parameter Validation**: All parameters should be validated appropriately
- **Error Handling**: Error handling should be consistent and clear
- **Documentation**: Function behavior should be well-documented

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