ousterhout-build-deep

SKILL.md

---
name: ousterhout-build-deep
description: Używaj podczas pisania lub zmieniania kodu, przed oznaczeniem zadania jako zakończonego, za każdym razem, gdy zmiana dodaje eksportowaną lub importowalną nazwę, tworzy moduł, klasę, komponent, pomocnika, hook, usługę lub wrapper, albo centralizuje powtarzający się kod. Lista kontrolna dla autora podczas tworzenia głębokich modułów: nazwij decyzję, którą ukrywa granica, przejdź testy głębokości i niezmienników, napraw problemy zamiast je przenosić, nigdy nie dziel tylko ze względu na rozmiar i zakończ krótką notatką projektową. Zwięzły towarzysz ousterhout-quality-program, który pozostaje pełnym narzędziem do przeglądu.
---

# Build it deep (Ousterhout, author-time)

Piszesz kod, a nie go przeglądasz. Uruchom to na własnej zmianie, zanim
uznasz zadanie za zakończone.

## 1. Bramka

Czy zmiana dodaje eksportowaną/importowalną nazwę, tworzy moduł, klasę,
komponent, helper, hook, serwis lub wrapper albo centralizuje powtarzający się kod?
Jeśli nie, pomiń tę umiejętność. Zmiany nazw, codemody, edycje konfiguracji/danych i jednowierszowe
poprawki są wyłączone.

## 2. Zanim napiszesz granicę

- Znajdź, jak to repozytorium już rozwiązuje problem o takim kształcie i postępuj według tego,
  chyba że potrafisz uzasadnić inaczej. Przeczytaj aktualną dokumentację i typy zależności:
  API przypominane z pamięci to twierdzenie, nie źródło.
- Najpierw napisz komentarz interfejsu: co obiecuje, co ukrywa. Jeśli nie potrafisz nazwać ukrytej decyzji
  (format, polityka, reguła, wybór schematu), granica nie powinna istnieć. Wstaw ją inline.
- Nazwij to językiem domeny. Jeśli jedyną uczciwą nazwą jest `utils`, `helpers` lub `manager`,
  podział jest w złym miejscu.

## 3. Dwa testy

- **Głębokość.** Interfejs musi ukrywać znacznie więcej niż eksponuje. Wrapper przekazujący argumenty
  to koszt bez korzyści; usuń go.
- **Niezmiennik.** Wyodrębnij wspólny kod tylko wtedy, gdy chroni wspólną regułę.
  Dowodem jest współzmiana: kopie były poprawiane lub zmieniane razem w historii.
  Podobne fragmenty, które zmieniają się niezależnie, pozostają zdublowane.

## 4. Poprawka musi usunąć problem, a nie go przenosić

- Sześć rzutowań przeniesionych do jednego generycznego helpera to nadal sześć rzutowań.
  Napisz typowany mapper, który rzutowania maskowały.
- Nie dodawaj parametru ani flagi, które przerzucają decyzję na wywołujących, chyba że
  wywołujący naprawdę wiedzą coś, czego ty nie wiesz. Wchłon trudny przypadek wewnątrz.
- Preferuj semantykę, w której przypadek błędu nie może wystąpić, zamiast każdemu wywołującemu
  kazać go obsłużyć.
- Przenoszenie istotnej złożoności domenowej do innego pliku to nie jest uproszczenie.

## 5. Pod presją "posprzątaj to" lub "ten plik jest za duży"

Nigdy nie dziel tylko ze względu na rozmiar. Jeden moduł o długości 400 linii ukrywający jedną decyzję
jest lepszy niż cztery moduły po 100 linii przeciekające te same połączenia.
Zapytaj, jaką decyzję ukrywa każdy podział; jeśli żadnej, nie dziel.

## 6. Bezpieczeństwo

Istniejący kod: zabezpiecz aktualne zachowanie testem przed pogłębieniem.
Nowy kod: napisz test definiujący zamierzone zachowanie.

## 7. Raport

Jeśli bramka zadziałała, zakończ swoją końcową wiadomość 2-4 linijkową notatką projektową:
każda dodana granica i decyzja, którą ukrywa; duplikacja pozostawiona celowo i dlaczego;
wszystko powierzchowne, co zaakceptowałeś i dlaczego.

Dla spornego przypadku lub pełnego przeglądu załaduj `ousterhout-quality-program`.

Tagi