𝗠𝘆 𝗥𝗘𝗔𝗗𝗠𝗘 𝗦𝗮𝗶𝗱 𝟴𝟬 𝗧𝗼𝗼𝗹𝘀. 𝗠𝘆 𝗖𝗼𝗱𝗲 𝗛𝗮𝗱 𝟵𝟲. 𝗡𝗼𝗯𝗼𝗱𝘆 𝗡𝗼𝘁𝗶𝗰𝗲𝗱 𝗙𝗼𝗿 𝗪𝗲𝗲𝗸𝘀.

Açık kaynaklı bir proje yürütüyorum. AI ajanları için tarayıcı otomasyonu kullanıyor.

README dosyam projenin 80 aracı olduğunu söylüyordu. Bu sayıyı sloganıma, navigasyona ve sosyal medya metinlerine eklemiştim.

Geçen hafta bir denetim yaptım. README dosyamı gerçek kodumla karşılaştırdım.

Kod 96 araç tespit etti.

Tek bir dosyada üç farklı gerçeklik vardı:

  • Pazarlama rakamı: 80
  • Dokümante edilmiş liste: 83
  • Gerçek kod: 96

On üç araç tamamen dokümante edilmemişti. Kullanıcılar bunların varlığından haberdar değildi.

En tehlikeli kısım aradaki boşluktu. Bu dokümante edilmemiş araçlardan dördü üst düzey sistem araçlarıydı. Klavye ve fareyi kontrol etmek için işletim sistemi düzeyindeki olayları kullanıyorlardı. Bu, projemin en güçlü ve hassas kısmı.

Bu bana dokümantasyon sapması (documentation drift) hakkında acı bir ders verdi.

Sapma rastgele değildir. Taraflıdır. Kolay ve sıkıcı şeyleri dokümante edersiniz. Aceleyle sunduğunuz yeni, güçlü veya hassas araçları dokümante etmeyi unutursunuz.

Bir projenin en riskli kısmını bulmak istiyorsanız dokümanları okumayın. Dokümanlar ile kod arasındaki boşluğa bakın.

Sayıyı düzeltmeye çalıştım. Bu bir hataydı. Sayıyı düzeltmek sadece semptomu tedavi eder.

Sorun manuel bakımdır. Eğer bir insan bir bilgiyi elle yazarsa, o bilgi eninde sonunda yanlış hale gelecektir.

Tek gerçek çözüm, sayının yanlış olmasını imkansız hale getirmektir.

Bilgileri doğruluk kaynağından (source of truth) türetmelisiniz.

Projemin zaten bir çözümü vardı: smoke test. Test, sunucuya kaç aracı olduğunu sorar ve sayıyı kontrol eder. Hardcoded bir sayı kullanmaz. Test asla sapma göstermez çünkü asla statik bir sayı saklamaz.

Yazım konusunda daha disiplinli olmaya çalışmayı bırakın. Disiplin başarısız olur. Bunun yerine, bilgilerinizi otomatize edin:

  • Derleme sırasında bir betik kullanarak sayıları oluşturun.
  • Araç listelerini doğrudan kod kaydınızdan (code registry) oluşturun.
  • İnsanları sadece anlatım ve açıklamalar için kullanın.

Eğer bir bilgi türetilebiliyorsa, onu elle yazmayın. Bu, sadece gerçekleşmeyi bekleyen bir sapmadır.

Bugün kendi projenizde bu denetimi yapın:

  1. Kodunuzdaki gerçek öğeleri sayın.
  2. Dokümantasyonunuzun iddia ettiği şeyleri sayın.
  3. Eğer uyuşmuyorlarsa, o boşlukta ne olduğunu bulun.

Boşluktaki öğeler genellikle projenizin en önemli kısımlarıdır.

Kaynak: https://dev.to/achiya-automation/my-readme-said-80-tools-my-code-had-96-nobody-noticed-for-weeks-1f3e

İsteğe bağlı öğrenme topluluğu: https://t.me/GyaanSetuAi