single-purpose-variables

obra's avatarfrom obra

Use each variable for exactly one purpose - no hybrid coupling or hidden meanings

⭐29stars🔀23forks📁View on GitHub🕐Updated Oct 9, 2025

When & Why to Use This Skill

This Claude skill enforces the 'Single Purpose Variables' principle, a fundamental clean code practice that ensures every variable represents exactly one distinct concept. By eliminating hybrid coupling—where a variable might represent a value in one context and an error flag in another—this skill significantly enhances code readability, reduces cognitive load for developers, and prevents subtle logic bugs associated with variable reuse and hidden meanings.

Use Cases

  • Refactoring legacy code to separate variables that serve dual purposes, such as using -1 to indicate an error in a count variable.
  • Replacing 'magic numbers' and hidden logic (e.g., IDs over a certain value implying a specific status) with explicit, descriptive boolean variables.
  • Improving algorithmic clarity by replacing reused generic 'temp' variables with uniquely named variables for each intermediate calculation step.
  • Standardizing code quality during automated code reviews to ensure that variable meanings remain consistent and transparent throughout the execution flow.
nameSingle Purpose Variables
descriptionUse each variable for exactly one purpose - no hybrid coupling or hidden meanings
when_to_useWhen writing any code with variables. When variable represents different things at different times. When -1 or special values indicate errors. When reusing temp for unrelated purposes. When variable meaning changes. When hybrid coupling exists. When pageCount=-1 means error not count.
version1.0.0
languagesall

Single Purpose Variables

Overview

Each variable should represent exactly ONE thing. No reusing for different purposes. No hidden meanings.

Core principle: If variable represents count sometimes and error other times, use two variables.

Baseline Violation: Hybrid Coupling

From baseline, agents use special values to indicate errors:

❌ Hybrid coupling (baseline):

def process_file_pages(filename):
    try:
        pages_processed = 0  # Count (integer purpose)
        # ... processing ...
        return pages_processed
    except:
        return -1  # Error flag (boolean purpose as -1)

Problem: pages_processed represents TWO things:

  • Non-negative integer = page count
  • -1 = error occurred

This is hybrid coupling: Variable moonlights as different type.

✅ Separate concerns:

def process_file_pages(filename):
    try:
        pages_processed = 0
        # ... processing ...
        return (True, pages_processed)  # Success, count
    except Exception as e:
        return (False, str(e))  # Failure, error message

Or raise exception:

def process_file_pages(filename):
    # Let exceptions propagate - no hybrid variable needed
    pages_processed = 0
    # ... processing (raises on error) ...
    return pages_processed  # Always a count, never an error

Common Hidden Meanings

❌ What agents naturally do:

page_count = 15  # Number of pages
page_count = -1  # Wait, now it means error!

customer_id = 1234  # Customer number
customer_id = 500001  # Wait, > 500000 means delinquent (subtract 500000)!

bytes_written = 1024  # Bytes written
bytes_written = -5  # Wait, negative means disk drive number!

✅ Separate variables:

page_count = 15
processing_failed = True  # Separate boolean for error state

customer_id = 1234
is_delinquent = False  # Separate boolean for status

bytes_written = 1024
disk_drive = 5  # Separate variable for drive number

Legitimate Variable Reuse

Good reuse (same purpose, same meaning):

# ✅ GOOD: total_sales used for multiple related calculations
total_sales = sum(sales)
average = total_sales / len(sales)  # Same value, same meaning
percentage = (total_sales / target) * 100  # Same value, same meaning

Bad reuse (different purposes):

# ❌ BAD: temp reused for unrelated purposes
temp = sqrt(b*b - 4*a*c)  # Discriminant
root1 = (-b + temp) / (2*a)
# ...
temp = root1  # Now reused for swapping (different purpose!)
root1 = root2
root2 = temp

✅ Separate variables:

discriminant = sqrt(b*b - 4*a*c)  # Clear purpose
root1 = (-b + discriminant) / (2*a)
# ...
old_root = root1  # Clear purpose (swapping)
root1 = root2
root2 = old_root

Quick Reference

Violation Example Fix
Hybrid coupling count=-1 means error Separate: count + error_occurred boolean
Hidden meanings id > 500000 means delinquent Separate: id + is_delinquent
Temp reuse temp for discriminant, then swapping Use: discriminant, old_root
State changes Variable means X, then means Y Two variables with clear names

Red Flags

  • Variable represents different types (integer sometimes, boolean as -1)
  • Special values have hidden meanings (-1, 0, null mean different things)
  • Reusing temp, result, value for unrelated purposes
  • Code comments explain "if X then it means Y, else Z"
  • Must remember what value currently means

Fix: Create separate variable with clear name for each purpose.

Real-World Impact

From Code Complete:

  • Hybrid coupling creates confusion
  • Even if clear to you, won't be to others
  • Extra variable costs nothing, clarity is priceless

From baseline:

  • Agent used -1 to indicate error in count variable (hybrid coupling)

With this skill: Separate variables for separate purposes.

Integration with Other Skills

For naming clarity: See skills/naming-variables - each purpose needs its own well-named variable