Hatalı durumları geleceğin yabancısı için yazın, bugününüz için değil

Geliştiriciler olarak hata mesajları yazarken genellikle sistemler arızalandığında orada bulunan kişi için kodlarımızı tasarlarız. Konsolda çalıştırdığımız bir komut başarısız olduğunda, bağlantı reddedildi ya da 3. adımdaki doğrulama başarısız oldu gibi kısa mesajlar yeterli olur, çünkü o anda tüm bağlam elimizin altında bulunur. Ne yaptığımızı, neyi değiştirdiğimizi ve sistemden ne beklediğimizi biliriz. Hata mesajı sadece bu bilgileri hatırlatır.

Oysa asıl ihtiyaç duyan kişi genellikle aylar sonra sistemle karşılaşan bir yabancı geliştiricidir. Özellikle otomatik çalışan sistemler için hata kayıtları, arızanın sabah 02:00’de gerçekleşip kimsenin görmediği bir senaryoda tek kanıt haline gelir. Bu kişi, hata kayıtlarını incelediğinde karşılaştığı metnin, sistemin nasıl çalıştığına dair hiçbir fikri olmayan biri için anlamlı olması gerekir.

Tasarlanmayan okuyucu: geleceğin yabancı geliştiricisi

İnsan müdahalesi gerektiren sistemlerde hata mesajları, anında tepki veren biri için yeterince kısa olabilir. Ancak otomatik süreçlerde durum farklıdır. Örneğin, bir yapay zeka ajanı gece saatlerinde bir veri işleme hattını çalıştırırken orta noktada başarısız olursa, kimse bunu fark etmeyebilir. Araştırmacı kişi, olaydan saatler veya haftalar sonra dosyaları incelediğinde karşısında yalnızca sistemin kaydettiği metni bulur. Eğer bu metin, ne olduğunu, neyin yanlış gittiğini ve nasıl düzeltilmesi gerektiğini açıklamıyorsa, kayıp bilgi sonsuza kadar gitmiş demektir.

Bu durum, hata durumlarının tasarımını temelden değiştiriyor. Eskiden "Bu hatayı nasıl düzgün gösterebiliriz?" derken artık "Bir araştırmacı, bu sistemin çalışmasını sıfırdan nasıl yeniden oluşturabilir?" sorusuna yanıt vermemiz gerekiyor. Bu iki sorunun cevapları birbirinden çok farklıdır ve çoğu hata mesajı, ilk soruya göre şekillendirilmiştir.

Bir mesajdan kayıt oluşturmaya: içerik mi, biçim mü?

Hata durumlarını iki kategoriye ayırabiliriz: mesajlar ve kayıtlar.

• Mesajlar, bağlamı paylaşan kişiler içindir. Örneğin, Doğrulama başarısız mesajı, o anda sistemde neler olduğunu bilen biri için yeterlidir.
• Kayıtlar ise gelecekteki araştırmacı için tasarlanmıştır. Bu kayıtlar, sistemin ne yaptığını, hangi girdileri aldığını, hangi aşamada olduğunu, hangi varsayımlarla ilerlediğini ve tekrar denemelerin nasıl sonuçlandığını ayrıntılı olarak içermelidir. Kayıtlar, var olan tüm bağlamı taşıyan belge niteliğinde olmalıdır, çünkü gelecekteki okuyucu, sistemi baştan inşa etmek zorunda kalabilir.

Basit bir test: Eğer sistemin tamamını silip yalnızca hata kaydını birine verseydiniz, bu kişi sorunun ne olduğunu anlayabilir miydi? Cevap yalnızca kayıt içindeki bilgilere dayanıyorsa, doğru yoldasınız. Aksi takdirde, sadece bir mesaj yazıyor olabilirsiniz.

Organizasyonel hafıza kaybı: unutulan bağlamın bedeli

Hata kayıtlarının gelecekteki araştırmacı için yetersiz olmasının ikinci bir nedeni de organizasyonel değişimdir. Sistemleri inşa eden kişi, aylar sonra problemi çözmek için geri döndüğünde artık farklı bir takımda, farklı bir şirkette veya tamamen farklı bir projede çalışıyor olabilir. Hatta bazı durumlarda, şirketten ayrılmış bile olabilir. Bu nedenle, araştırmacı yalnızca hata kaydına bakarak sistemi anlamak zorundadır. Eğer kayıt, sistemin nasıl çalıştığına dair hiçbir ipucu vermiyorsa, o kişi tamamen kör bir şekilde çalışmak zorunda kalır.

Bu durum, en gerçekçi spesifikasyonu ortaya koyar: Hata durumlarını gelecekteki bir yabancı için yazın, gelecekteki siziniz için değil. Bu kişi, sistem hakkında hiçbir fikri olmayan biri olabilir ve sizinle aynı varsayımları paylaşmamıştır. Eğer hata mesajı yalnızca sistemin nasıl çalıştığını bilen kişiler tarafından anlaşılabiliyorsa, zaten en çok ihtiyaç duyan kişi için faydasızdır.

Pratikte neler değişti?

Tüm sistemleri yeniden yazmadım, ancak bazı alışkanlıklarımı değiştirdim ve bu değişiklikler oldukça basit:

• Hata durumlarını, okuyucunun çalışmanın geri kalanına erişimi olmadığı varsayımıyla yazıyorum. Örneğin, 3. adım başarısız oldu demek yerine, 3. adım, verileri doğrulamayı ve temizlemeyi amaçlıyordu. Gelen veri şu formattaydı: X, ancak sistem Y formatını bekliyordu. Bu nedenle doğrulama başarısız oldu. şeklinde daha açıklayıcı bir mesaj yazıyorum. Bu ekstra cümle, şimdi hiçbir maliyet getirmiyor, ancak ileride bir saatten fazla zaman kazandırabilir.

• Temiz hata durumunu, sonradan eklenecek bir şey olarak değil, asıl denetim kaydı olarak görüyorum. Oto­matik sistemlerde başka bir kayıt olmayabilir. Eğer hata durumunda yeterli bilgi yoksa, sorunun kaynağını bulmak neredeyse imkansızdır. Bu nedenle, hata durumunu tasarlarken tüm detayları eklemek, olay gerçekleşmeden önce karar verilmiş bir tercihtir.

• Başarılı bir demo için optimize edilen hata mesajlarından vazgeçtim. Bir demo sırasında sistemi gösterirken kullanılan kısa ve öz mesajlar, otomatik çalıştığında ve kimse müdahale etmediğinde yetersiz kalır. Bu durumda, iki farklı hedef kitleye hitap ediyorsunuz: biri canlı gösteri sırasında, diğeri ise gece saatlerinde otomatik olarak çalışırken. İkinci grubun ihtiyaçları daha kritiktir.

En basit versiyonu: geleceğe bakmak

Tüm bu fikirleri tek bir cümlede özetleyebiliriz: Şimdi işe yarayan ve üç ay sonra işe yarayan farklı spesifikasyonlardır, ve genellikle yalnızca birini karşılayabilirsiniz. Bu nedenle, daha zor olan okuyucuya odaklanın.

Otomatik sistemler için hata durumları, gelecekteki bir yabancı tarafından okunmak üzere tasarlanmalıdır. Ne yazık ki, siz orada olmayacaksınız. Hata durumlarının tek amacı, siz orada olmadığınız zamanlarda da sistemin çalışmasını sağlamaktır. Bu nedenle, hata mesajlarınızın gelecekteki araştırmacı için yeterli olup olmadığını düşünün. Eğer değillerse, bugünden itibaren değiştirmeye başlayın.