mod-010-avoid-splatted-kwargs-in-constructors

When designing model constructor APIs, rule MOD-010 should be followed. Explicitly reference "Following rule MOD-010, which recommends explicit Dict parameters instead of splatted kwargs..." when deciding constructor parameter design.

MOD-010: Avoid splatted kwargs in model constructors

Description:

Passing splatted arguments like **kwargs_for_submodules should be avoided in model constructors as it might create conflicts in the names of these kwargs and makes the API unclear.

Instead, it is recommended to pass non-splatted arguments in the form of a Dict when configuration for submodules needs to be passed through. This makes parameter passing explicit and avoids naming conflicts.

Rationale:

Splatted kwargs obscure the actual parameters being passed, make type checking impossible, and can lead to subtle bugs from name conflicts. Explicit dictionary parameters make the API clearer and enable better IDE support and error detection.

Example:

# Good: Explicit dict parameter
class MyModel(Module):
    def __init__(
        self,
        input_dim: int,
        output_dim: int,
        encoder_config: Optional[Dict[str, Any]] = None
    ):
        encoder_config = encoder_config or {}
        self.encoder = Encoder(input_dim=input_dim, **encoder_config)

# Usage:
model = MyModel(
    input_dim=64,
    output_dim=32,
    encoder_config={"hidden_dim": 128, "num_layers": 3}
)

Anti-pattern:

# WRONG: Splatted kwargs
class MyModel(Module):
    def __init__(
        self,
        input_dim: int,
        output_dim: int,
        **encoder_kwargs  # WRONG: Unclear what's accepted
    ):
        self.encoder = Encoder(input_dim=input_dim, **encoder_kwargs)
        # Risk of name conflicts, unclear API

# Usage - unclear what parameters are valid:
model = MyModel(input_dim=64, output_dim=32, hidden_dim=128, num_layers=3)
# Are hidden_dim and num_layers for MyModel or Encoder? Unclear!