kitchen-engineer42/pdf2skills/routine-parameter-design

Routine Parameter Design

Use this skill when defining new functions, refactoring existing method signatures, or designing API interfaces to ensure proper parameter design.

When to Use

• Defining or refactoring a function's parameter list
• Designing API interfaces or method signatures
• Reviewing code for parameter-related issues
• Optimizing function interfaces for clarity and maintainability

Core Design Principles

1. Limit Parameter Count

• Minimize the number of parameters to improve readability and usability
• Consider using parameter objects or structs when parameters exceed 3-5 items
• Each parameter should serve a distinct, necessary purpose

2. Order Parameters (Input-Modify-Output)

Arrange parameters in this specific sequence:

1. Input parameters: Data the routine reads but does not modify
2. Modify parameters: Data the routine both reads and modifies
3. Output parameters: Data the routine writes but does not read

3. Choose Appropriate Pass Mechanisms

• Pass by value: For primitive types and small objects that won't be modified
• Pass by reference: For objects that need modification or to avoid copying overhead
• Objects: Typically passed as object references (not individual fields)
• Pointers: Follow the asterisk rule (use * consistently for pointer parameters)

4. Ensure Interface Consistency

• Match actual parameters with formal parameter types
• Follow language-specific conventions (e.g., C library ordering when applicable)
• Maintain consistent ordering across related functions
• Use similar parameter names for similar purposes across the codebase

5. Apply Modifiers Appropriately

• Use const prefix to prevent modification of input parameters
• Use in keyword to explicitly mark input-only parameters
• Use out keyword to explicitly mark output-only parameters
• Consider inout or equivalent for parameters that are both read and modified

6. Document and Name Clearly

• Use descriptive, self-documenting parameter names
• Write clear comments explaining parameter purpose and constraints
• Document expected ranges, valid values, and edge cases
• Include units of measurement when applicable

7. Validate Parameter Usage

• Ensure the routine uses all passed parameters
• Remove unused parameters to avoid confusion
• If a parameter is temporarily unused, document why and when it will be used

8. Avoid Global Variables

• Never use global variables as substitutes for parameters
• Pass all required data explicitly through the parameter list
• Global variables make code harder to test, understand, and maintain

Language-Specific Considerations

• C/C++: Pay attention to pointer vs reference semantics, const correctness
• Java: All objects are passed by reference; primitives by value
• Visual Basic: Use ByVal and ByRef keywords explicitly
• Always check language-specific syntax limitations and conventions

Review Checklist

• [ ] Parameter count is minimized and reasonable
• [ ] Parameters follow input-modify-output ordering
• [ ] Pass mechanism is appropriate for each parameter
• [ ] Modifiers (const, in, out) are used correctly
• [ ] All parameters have clear names and documentation
• [ ] All parameters are actually used by the routine
• [ ] No global variables are used as parameter substitutes
• [ ] Interface is consistent with related functions