Numbered Block Parameters

When to Use vs. Avoid

class BestPracticesDemo
  def self.good_uses
    puts "=== Good Uses of Numbered Parameters ==="

    data = [1, 2, 3, 4, 5]

    # ✅ Simple mathematical operations
    squares = data.map { _1 ** 2 }
    puts "Squares: #{squares}"

    # ✅ Property access
    users = [{ name: "Alice" }, { name: "Bob" }]
    names = users.map { _1[:name] }
    puts "Names: #{names}"

    # ✅ Simple filtering
    evens = data.select { _1.even? }
    puts "Evens: #{evens}"

    # ✅ Chaining operations
    result = data.map { _1 * 2 }.select { _1 > 5 }.map { _1.to_s }
    puts "Chained: #{result}"
  end

  def self.problematic_uses
    puts "\n=== Avoid These Patterns ==="

    data = [1, 2, 3, 4, 5]

    # ❌ Complex logic (better with named parameters)
    def self.complex_bad_example
      data.map do
        if _1 < 3
          result = _1 * 2
          result += 1 if _1.odd?
          result.to_s.ljust(5, "0")
        else
          (_1 ** 2 + _1).to_s.reverse
        end
      end
    end

    # ✅ Better version with named parameter
    def self.complex_good_example
      data.map do |num|
        if num < 3
          result = num * 2
          result += 1 if num.odd?
          result.to_s.ljust(5, "0")
        else
          (num ** 2 + num).to_s.reverse
        end
      end
    end

    puts "Complex logic results:"
    puts "Bad (numbered):  #{complex_bad_example}"
    puts "Good (named):    #{complex_good_example}"

    # ❌ Multiple nested levels
    nested_data = [[1, 2], [3, 4], [5, 6]]

    # This becomes hard to read
    flattened_bad = nested_data.map { _1.map { _1 * 2 } }.flatten
    puts "\nNested numbered: #{flattened_bad}"

    # Better with named parameters
    flattened_good = nested_data.map { |pair| pair.map { |num| num * 2 } }.flatten
    puts "Nested named: #{flattened_good}"
  end

  def self.migration_example
    puts "\n=== Migration Strategy ==="

    # Start with traditional syntax
    data = ["hello", "world", "ruby"]

    # Step 1: Identify simple transformations
    traditional = data.map { |word| word.upcase }

    # Step 2: Convert to numbered parameters
    numbered = data.map { _1.upcase }

    # Step 3: Verify behavior is identical
    puts "Traditional: #{traditional}"
    puts "Numbered:    #{numbered}"
    puts "Same result: #{traditional == numbered}"

    # Step 4: Consider readability
    # For teams new to numbered parameters, document the change
    # and ensure everyone understands the syntax
  end

  def self.performance_considerations
    puts "\n=== Performance Considerations ==="

    require 'benchmark'

    large_array = (1..100_000).to_a

    # Performance is generally equivalent
    Benchmark.bm(20) do |x|
      x.report("Named parameter") do
        large_array.map { |n| n * 2 }.first(1000)
      end

      x.report("Numbered parameter") do
        large_array.map { _1 * 2 }.first(1000)
      end
    end

    puts "\nPerformance is typically equivalent."
    puts "Choose based on readability, not performance."
  end
end

BestPracticesDemo.good_uses
BestPracticesDemo.problematic_uses
BestPracticesDemo.migration_example
# BestPracticesDemo.performance_considerations  # Uncomment to run benchmark