ousterhout-build-deep

SKILL.md

---
name: ousterhout-build-deep
description: Gebruik tijdens het schrijven of wijzigen van code, voordat je de taak als voltooid markeert, telkens wanneer de wijziging een geëxporteerde of importeerbare naam toevoegt, een module, klasse, component, helper, hook, service of wrapper creëert, of herhaalde code centraliseert. Checklist voor de auteur bij het bouwen van diepe modules: benoem de beslissing die de grens verbergt, doorsta de diepte- en invarianttests, los problemen op in plaats van ze te verplaatsen, splits nooit alleen op basis van grootte, en sluit af met een korte ontwerpaantekening. Compacte aanvulling op ousterhout-quality-program, dat het volledige beoordelingskader blijft.
---

# Build it deep (Ousterhout, author-time)

Je bent code aan het schrijven, niet aan het reviewen. Voer dit uit op je eigen wijziging voordat
je de taak als voltooid beschouwt.

## 1. Poort

Voegt de wijziging een geëxporteerde/geïmporteerde naam toe, maakt het een module, klasse,
component, helper, hook, service of wrapper, of centraliseert het herhaalde code?
Zo nee, sla deze vaardigheid over. Hernoemingen, codemods, config/data-bewerkingen en éénregelige
oplossingen zijn uitgezonderd.

## 2. Voordat je de grens schrijft

- Zoek hoe deze repo al een probleem van deze vorm oplost en volg dat
  tenzij je kunt aangeven waarom niet. Lees de huidige documentatie en
  types van de afhankelijkheid: een API uit het geheugen ophalen is een bewering, geen bron.
- Schrijf eerst de interfacecommentaar: wat het belooft, wat het verbergt. Als
  je de verborgen beslissing (een formaat, een beleid, een regel, een
  schema-keuze) niet kunt benoemen, mag de grens niet bestaan. Zet het inline.
- Noem het in domeintaal. Als de enige eerlijke naam `utils`,
  `helpers` of `manager` is, zit de scheiding op de verkeerde plek.

## 3. Twee tests

- **Diepte.** De interface moet substantieel meer verbergen dan het blootlegt. Een
  wrapper die zijn argumenten doorgeeft is een kostenpost zonder voordeel; verwijder het.
- **Invariant.** Extraheer gedeelde code alleen als het een gedeelde regel beschermt.
  Het bewijs is co-verandering: de kopieën werden samen in de geschiedenis gefixt of veranderd.
  Gelijken die onafhankelijk veranderen blijven gedupliceerd.

## 4. Een fix moet het probleem verwijderen, niet verplaatsen

- Zes casts die in één generieke cast-helper worden verplaatst zijn nog steeds zes casts.
  Schrijf de getypte mapper waar de casts overheen plakten.
- Voeg geen parameter of vlag toe die een beslissing aan aanroepers doorschuift tenzij
  aanroepers echt iets weten wat jij niet weet. Neem het lastige geval binnenin op.
- Geef de voorkeur aan semantiek waarbij de foutcase niet kan optreden boven het elke
  aanroeper laten afhandelen.
- Essentiële domeincomplexiteit naar een ander bestand verplaatsen is geen vereenvoudiging.

## 5. Onder druk van "maak dit schoon" of "dit bestand is te groot"

Splits nooit alleen op grootte. Eén module van 400 regels die één beslissing verbergt is beter
dan vier modules van 100 regels die dezelfde verbindingen lekken. Vraag welke beslissing elke
splitsing verbergt; als geen, splits dan niet.

## 6. Veiligheid

Bestaande code: veranker het huidige gedrag met een test voordat je het verdiept. Nieuwe
code: schrijf de test die het bedoelde gedrag definieert.

## 7. Rapport

Als de poort afging, eindig je je laatste bericht met een ontwerpnotitie van 2-4 regels: elke
grens die je hebt toegevoegd en de beslissing die het verbergt; duplicatie die je bewust hebt
achtergelaten en waarom; alles oppervlakkigs dat je hebt geaccepteerd en waarom.

Voor een betwiste beslissing of een volledige review, laad `ousterhout-quality-program`.

Tags