Yazılım mühendisliğinde herkesin nefret ettiği ama herkesin ihtiyaç duyduğu bir şey vardır: Dokümantasyon. Kod yazmak heyecanlıdır, debugging dedektiflik gibidir, deploy yapmak adrenalin verir. Ama dokümantasyon yazmak? O, herkesin "sonra yaparız" deyip asla yapmadığı, sıkıcı ve zahmetli bir iştir.

Altı ay önce yazdığım bir kodu açtığımda o kodun ne yaptığını anlayamadığım anı çok net hatırlıyorum. Kendi yazdığım kod. Kendi kafamdan çıkan mantık. Ve karşımda, hiçbir yorum satırı (comment) olmayan, değişken isimleri anlamsız (x, temp, data2) olan ve neyi neden yaptığı hakkında tek bir ipucu bırakmadığım bir dosya duruyordu. O an kendime çok kızdım ve "Bu kodu yazan adam kim? Ah, benmişim" dediğim anı asla unutmayacağım.

O gün bir şeyi anladım: Dokümantasyon, başkaları için yazılmaz. Dokümantasyon, altı ay sonraki kendiniz için yazılır. O gelecekteki siz, bugünkü bağlamı (context), kararların arkasındaki nedenleri ve o kodun neden böyle yazıldığını tamamen unutmuş olacaktır. Ve o an, geçmişteki kendinizin bıraktığı o küçük not, o açıklama satırı, o README dosyası hayatınızı kurtaracaktır.

Bu yüzden ben dokümantasyona "aşk mektubu" diyorum. Gelecekteki kendinize veya sizden sonra o koda dokunacak olan ekip arkadaşınıza yazdığınız bir mektuptur: "Merhaba, bu kodu şu tarihte, şu nedenle yazdım. Burada X yerine Y kullanmamın sebebi şuydu. Eğer Z'yi değiştirmek istersen, dikkat et çünkü şu servis buna bağımlı."

İyi bir dokümantasyon neye benzer? "Ne" yazdığınızı değil, "neden" yazdığınızı anlatır. Kodun kendisi zaten "ne" yaptığını gösterir. Ama "neden" bu yaklaşımı seçtiğinizi, hangi alternatifleri deneyip elediğinizi ve hangi kısıtlamalar (constraints) altında bu kararı verdiğinizi sadece siz bilirsiniz. Ve bu bilgiyi yazmazsanız, sonsuza kadar kaybolur.

Suku Tech'te dokümantasyon yazmak bir lüks veya opsiyonel bir görev değil, kodun ayrılmaz bir parçasıdır. Pull Request (kod inceleme talebi) açarken, eğer ilgili dokümantasyon güncellenmemişse o PR reddedilir. Bu kuralı ekibe ilk koyduğumda herkes söylendi. "Ama zaman kaybı!" "Ama deadline'a yetişmemiz lazım!" Evet, dokümantasyon yazmak bugün 30 dakikanızı alır. Ama o 30 dakikayı yazmazsanız, altı ay sonra o kodu anlamaya çalışan birileri (veya kendiniz) 3 gün harcayacaktır.

Bir kod deposunun (repository) gerçek kalitesini anlamak istiyorsanız, koduna değil dokümantasyonuna bakın. İyi dokümante edilmiş bir proje, o projenin arkasında düşünen, önemseyen ve gelecekteki insanlara saygı duyan bir ekip olduğunun kanıtıdır. Kodunuz bir gün silinebilir, yeniden yazılabilir. Ama bıraktığınız notlar, bilgi ve bağlam kalıcıdır. Gelecekteki kendinize bugün bir aşk mektubu yazın.

teamwork

Dokümantasyon Yazmak Bir Aşk Mektubudur: Gelecekteki Kendine Not Bırakmak