Mój README mówił o 80 narzędziach. Mój kod miał ich 96. Przez tygodnie nikt tego nie zauważył.

Prowadzę projekt open-source. Wykorzystuje on automatyzację przeglądarki dla agentów AI.

Mój README mówił, że projekt posiada 80 narzędzi. Tę liczbę umieściłem w tagline'u, nawigacji i tekstach do mediów społecznościowych.

W zeszłym tygodniu przeprowadziłem audyt. Porównałem mój README z rzeczywistym kodem.

Kod rejestrował 96 narzędzi.

Miałem trzy różne prawdy w jednym pliku:

  • Liczba marketingowa: 80
  • Udokumentowana lista: 83
  • Rzeczywisty kod: 96

Trzynaście narzędzi było całkowicie nieudokumentowanych. Użytkownicy nie wiedzieli o ich istnieniu.

Najniebezpieczniejsza była ta luka. Cztery z tych nieudokumentowanych narzędzi były wysokopoziomowymi narzędziami systemowymi. Wykorzystywały zdarzenia na poziomie systemu operacyjnego do kontrolowania klawiatury i myszy. To najpotężniejsza i najbardziej wrażliwa część mojego projektu.

To nauczyło mnie bolesnej lekcji na temat dryfu dokumentacji.

Dryf nie jest przypadkowy. Jest stronniczy. Dokumentujesz łatwe, nudne rzeczy. Zapominasz udokumentować nowe, potężne lub wrażliwe narzędzia, które wypuszczasz w pośpiechu.

Jeśli chcesz znaleźć najryzykowniejszą część projektu, nie czytaj dokumentacji. Spójrz na lukę między dokumentacją a kodem.

Próbowałem poprawić liczbę. To był błąd. Poprawienie liczby leczy jedynie objawy.

Problemem jest ręczne utrzymywanie danych. Jeśli człowiek wpisuje fakt, ten fakt w końcu stanie się nieprawdziwy.

Jedynym prawdziwym rozwiązaniem jest sprawienie, by podanie błędnej liczby było niemożliwe.

Musisz wywodzić fakty z jedynego źródła prawdy.

Mój projekt miał już jedno rozwiązanie: smoke test. Test pyta serwer, ile narzędzi posiada, i sprawdza ich liczbę. Nie używa on liczby zakodowanej na sztywno. Test nigdy nie ulegnie dryfowi, ponieważ nigdy nie przechowuje statycznej wartości.

Przestań próbować być bardziej zdyscyplinowanym w pisaniu. Dyscyplina zawodzi. Zamiast tego, zautomatyzuj swoje fakty:

  • Generuj liczby za pomocą skryptu podczas budowania projektu.
  • Generuj listy narzędzi bezpośrednio z rejestru kodu.
  • Używaj ludzi wyłącznie do tworzenia prozy i wyjaśnień.

Jeśli fakt można wywieść, nie wpisuj go ręcznie. To po prostu dryf, który tylko czeka, by wystąpić.

Przeprowadź taki audyt we własnym projekcie już dziś:

  1. Policz rzeczywiste elementy w swoim kodzie.
  2. Policz to, co deklaruje Twoja dokumentacja.
  3. Jeśli wyniki się różnią, sprawdź, co znajduje się w tej luce.

Elementy w luce to zazwyczaj najważniejsze części Twojego projektu.

Źródło: https://dev.to/achiya-automation/my-readme-said-80-tools-my-code-had-96-nobody-noticed-for-weeks-1f3e

Opcjonalna społeczność edukacyjna: https://t.me/GyaanSetuAi