C# generics deep dive

// BAD: Shared code path, potential boxing if T is constrained loosely
public void Process<T>(T value) { /* ... */ }

// GOOD: Specialized code path for value types
public void Process<T>(T value) where T : struct
{
    // JIT generates specific code for int, float, custom structs, etc.
}

public unsafe struct Buffer<T> where T : unmanaged
{
    private T* _ptr;
    private int _length;

    public void CopyTo(Span<T> destination)
    {
        // Direct memory copy, no boxing, no virtual calls
        new Span<T>(_ptr, _length).CopyTo(destination);
    }
}

Generic math enables writing algorithms that work across all numeric types without boxing or reflection. This relies on static abstract members in interfaces.

Architecture Decision: Use INumber<TSelf> for general numeric operations. For specific needs, use interfaces like IAdditionOperators<TSelf, TOther, TResult>.

public static class MathUtils
{
    // Works for int, double, float, decimal, BigInteger, etc.
    public static T Mean<T>(ReadOnlySpan<T> values) 
        where T : INumber<T>
    {
        T sum = T.Zero;
        foreach (var value in values)
        {
            sum += value; // Resolved at compile time, inlined by JIT
        }
        return sum / T.CreateTruncating(values.Length);
    }
}

4. Variance with Precision

Variance (in / out) is restricted to interfaces and delegates. Misuse leads to type safety violations.

• Covariance (out T): Safe for read-only access. IEnumerable<out T>.
• Contravariance (in T): Safe for write-only access (inputs). IComparer<in T>.

// Valid: Covariant interface
public interface IProducer<out T>
{
    T Produce();
}

// Invalid: Cannot use T as input in covariant interface
// public interface IBad<out T> { void Consume(T item); } 

5. Constraint Hierarchy and notnull

Use notnull to prevent nullability warnings and runtime null checks for both reference and value types.

public class Cache<TKey, TValue> 
    where TKey : notnull 
    where TValue : class
{
    // TKey cannot be null (enforced by compiler and runtime for structs)
    // TValue is reference type, allows null checks if needed
}

Pitfall Guide

1. Generic Type Explosion

Mistake: Creating generics with unconstrained type parameters used in collections, leading to thousands of instantiations (e.g., Dictionary<Type, List<SpecificDto>>). Impact: Bloats the JIT code cache, increases memory usage, and slows module loading. Best Practice: Limit instantiations. If you have many types, consider a non-generic base class with generic derived classes, or use object/dynamic at the boundary and cast internally.

2. default(T) vs default Confusion

Mistake: Using default(T) where T might be a reference type, expecting null, but inadvertently passing it to a method that doesn't handle nulls, or vice versa. Impact: NullReferenceException or logic errors. Best Practice: Use default keyword without type parameter where context allows. Explicitly check if (value == null) for reference types or use where T : struct to guarantee non-null.

3. new() Constraint Overhead

Mistake: Assuming where T : new() is free. While efficient, it requires the JIT to emit a call to the constructor. In tight loops, this can be slower than factory patterns or object pooling. Impact: Minor performance hit in extreme micro-optimization scenarios. Best Practice: For high-frequency creation, prefer ArrayPool<T> or ObjectPool<T> over new() constraints.

4. Variance Misapplication on Classes

Mistake: Attempting to make a class covariant or contravariant. Impact: Compiler error. Variance is only supported on interfaces and delegates. Best Practice: Define variance on the interface and implement it in the class.

// Correct pattern
public interface IHandler<in T> { void Handle(T command); }
public class CommandHandler : IHandler<ICommand> { ... }

5. Ignoring unmanaged for Interop

Mistake: Using struct constraints for P/Invoke or stackalloc when unmanaged is required. Impact: Runtime failure or inability to use unsafe features. Best Practice: Use unmanaged when you need direct memory access or fixed-size buffers.

6. Over-Constraining APIs

Mistake: Adding where T : IComparable, ICloneable, ISerializable when only IComparable is needed. Impact: Restricts usability; consumers cannot use types that don't implement unnecessary interfaces. Best Practice: Apply the Principle of Least Constraint. Only require what the method body uses.

7. Generic Math Interface Complexity

Mistake: Trying to implement INumber<T> manually for custom types without understanding the interface requirements. Impact: Compilation errors due to missing static abstract members. Best Practice: Use the GenericMath NuGet package for backporting or rely on built-in types. For custom types, implement the interface carefully, ensuring all operators are defined.

Production Bundle

Action Checklist

• Audit Boxing: Scan codebase for IEnumerable<object> or ArrayList; replace with generic equivalents constrained to struct where performance is critical.
• Verify JIT Specialization: Ensure value-type heavy algorithms use where T : struct to trigger code specialization.
• Adopt Generic Math: For numeric libraries, replace interface-based arithmetic with INumber<T> constraints to enable inlining.
• Check Variance: Review all generic interfaces; annotate in/out correctly to enable polymorphic usage without casts.
• Limit Instantiations: Analyze generic usage patterns; refactor unconstrained generics used in dictionaries to prevent type explosion.
• Apply notnull: Use notnull constraints on keys and critical parameters to eliminate null-check overhead and warnings.
• Benchmark: Use BenchmarkDotNet to compare generic implementations against non-generic baselines for critical paths.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-Frequency Numeric Ops	Generic Math + struct constraint	Enables JIT specialization and operator inlining.	High performance gain; low maintenance.
Polymorphic Collections	IEnumerable<out T>	Allows safe covariance for read-only access.	Zero runtime cost; improves API flexibility.
Object Creation in Loop	ObjectPool<T>	Avoids allocation pressure and new() overhead.	Reduces GC pressure significantly.
Interop / Buffers	where T : unmanaged	Permits stackalloc and direct memory access.	Critical for safety and performance in unsafe code.
Generic Repository	where T : class, new()	Standard EF Core pattern; balances flexibility and instantiation.	Standard overhead; acceptable for data access layers.

Configuration Template

Generic Math Service Template: Ready-to-use template for high-performance numeric processing.

using System.Numerics;

public interface INumericProcessor<T> where T : INumber<T>
{
    T Compute(ReadOnlySpan<T> input);
}

public class SumProcessor<T> : INumericProcessor<T> where T : INumber<T>
{
    public T Compute(ReadOnlySpan<T> input)
    {
        T result = T.Zero;
        foreach (var value in input)
        {
            result += value;
        }
        return result;
    }
}

// Usage:
// var processor = new SumProcessor<double>();
// double result = processor.Compute(dataSpan);

Quick Start Guide

1. Initialize Project:

   dotnet new console -n GenericsDeepDive
   cd GenericsDeepDive
   dotnet add package BenchmarkDotNet
   

2. Create Generic Class: Create GenericProcessor.cs with a method using INumber<T> and struct constraint.

   public static class Processor
   {
       public static T Process<T>(T value) where T : INumber<T> => value + T.One;
   }
   

3. Add Benchmark: Create Benchmarks.cs comparing Process<int> vs Process<double> vs non-generic baseline.

4. Run Analysis:

   dotnet run -c Release
   

   Observe zero allocations and consistent throughput across types, validating JIT specialization.

5. Integrate Constraints: Apply where T : notnull to any dictionary keys or critical parameters identified during review to enforce null safety.