Skip to content

Convention — §G discipline (extract from duplication, not prediction)

What it is

"§G" is the project's rule for when to extract a shared helper/abstraction: extract from observed duplication, never from predicted future use. Named after the section that introduced it in the MIQ-131 report and applied as the central methodology through MIQ-132 and MIQ-133. It is the reason the helpers catalog is short and the shared shapes are locked.

The rule

  • Don't extract on prediction. A brief that lists eight "reusable" candidates is a hypothesis, not a mandate. Most should stay inline until duplication actually appears. (Of MIQ-131's eight predicted candidates, only some were extracted; the rest were deliberately left inline.)
  • Rule of three. Extract at the third real consumer, not the first or second. SystemRowProtectedException<T> was extracted only when a third entity genuinely needed it (MIQ-133, PB-085).
  • Even past three, extract only if it reads cleaner. Hitting the numeric threshold isn't sufficient — the ComposeReferencedBody StringBuilder had four consumers but stayed inline because the inline form was clearer than any helper signature.
  • Lock the shape; don't make it leak. Once a shared abstraction exists (createLookupHooks, DeleteConfirmDialog), its shape is locked (MIQ-131 decision 39). If a new consumer would force a 7th parameter or a different verb, the right move is not to bend the abstraction — keep that consumer inline, or split the abstraction. Forcing unneeded parameters onto shared code is the "leaky abstraction" §G exists to prevent.

Why it's built this way

Premature abstraction is harder to undo than duplication. A helper extracted on prediction tends to grow speculative parameters for cases that never arrive, and every real consumer then pays for the ones that don't exist. Waiting for three real uses means the shape is grounded in fact, and locking the shape keeps later consumers from quietly degrading it.

How to apply it

When you notice repetition while building, ask in order:

  1. Is this the third real occurrence? If not, leave it inline.
  2. If yes, would a shared helper genuinely read cleaner than the inline code? If not, leave it inline and note why.
  3. If you extract, lock the shape. A future consumer that doesn't fit stays inline — it does not get to widen the signature.

Gotchas / constraints

  • A 4th (or Nth) consumer is not automatic grounds to extract — readability still governs.
  • "Keep it inline" is a valid, documented outcome — record the decision (e.g. "B1 CodeUniquenessChecker: 3 BU-explicit + 1 implicit = no clean signature; helper call longer than the inline check") rather than extracting reluctantly.
  • Locked shape means locked — adding a parameter "just for this one entity" is the regression §G guards against.

Build status

Available — applied as the explicit methodology across MIQ-131/132/133 (the §G sections and decision 39).

  • Helpers catalog — the helpers this rule did (and didn't) produce.
  • Audit-first discipline — the gate that records these extraction decisions.
  • Source: MIQ-131 report §G + decision 39; MIQ-132 / MIQ-133 reports §G sections (manpoweriq/docs/).