Dokümantasyon oluşturma kültürü
Bilim ile uğraşan kişilerin dokümantasyon konusunda çok hassas olduğunu buluş tarihi incelendiğinde net bir şekilde anlayabiliriz. Ancak günümüzde dünyamızı yiyen yazılım söz konusu olunca dokümantasyon aşaması ne yazık ki her zaman üvey evlat olarak görülmüştür. Bu sadece yazılım ekiplerinin bir sorunu olmaktan çıkıp, simülasyon ve geliştirme yapan makina, elektrik - elektronik, mekatronik mühendisliği gibi bir çok teknik alana da yayılmıştır.
Temel sebebi, hedeflenen projenin başarı ile tamamlanması için bir metrik olmamasıdır. Öyle ya da böyle, dokümantasyonsuz da sistem çalıştığı sürece kimsenin üzerinde "zaman kaybetmesi" istenmemektedir.
Ancak dokümantasyon oluşturma kültürünün bireysel ve ekiplere çok büyük yararının olduğu da bir gerçektir.
Bu arada dokümantasyon kültüründen kastım tabi ki de şu değildir;
float sensorData; // ondalıklı sensör verisi
Dokümantasyonun temelinde, bariz şekilde ortada olmayan yazılım geliştirme aşamalarının, tüm adımların ve kararların kayıt altına alınmasıdır. Dokümantasyonun detayını ve kalitesini bir örnekle tanımlamak gerekirse: Geliştirilmiş olan bir kütüphanenin, API'nin; bir başka ekip üyesi veya açık kaynaklı olduğunu düşünürsek, tamamen farklı bir kişinin kullanabilmesi için gereken tüm adımları içermesidir. Veya yine çok sık verilen bir diğer örnekle; bundan bir yıl sonra bu kod satırına geri dönmek zorunda kalsaydınız, neler olup bittiğini anlayabileceğiniz detayda bir dokümantasyona sahip olmaktır.
Bir dokümantasyon kültürü oluşturmak tahmin edilenden kolay olabilir. Ancak geliştiriciler arasında dokümantasyon oluşturmaya karşı bazı dirençler bulunmaktadır. Bunların en genel savunmalarını inceleyecek olursak:
Kod, kendi kendini dokümante eder
Yani "en mükemmel kodlama prensiplerini" kullanıyorsunuz. İşlev ve değişken adlarınız kolayca ayrıştırılabiliyor. Harika 🥳 ! Ama daha yolun yarısındayız. Kodumuzun "ne" yaptığını anlamak kolay olsa da, "neden"i anlamak daha zor olabilir.
Geliştiriciler olarak, yazdıklarımızın sezgisel olarak rahat algılandığına inanmayı tercih ederiz. Hedef kitlelerimize olduğundan daha fazla yetenek yüklemeyi seçeriz. Bu abartılı özgüven, zaman geçip kendi satırlarımızı okumaya başladığımızda, kendi kendimize "kızmakla" bile sonuçlanabilir.
Bu duruma bir diğer örnek de, kodumuzun içerisinde sonradan bulduğumuz veya ekibimizce bulunan bir hata ve düzeltme için geçerlidir. Yazdığımız sırada üzerinde çalıştığımız kısım tamamen net değilse, içimize sinmediyse veya örümcek hislerimiz devreye girdiyse; gelecekteki kendimize bir kod satırının neden yanlış olduğuna veya değişmesi gerektiğine dair bir ipucu bırakabiliriz. İleriki süreçte bu kısmı siz veya bir başkası incelerken oldukça faydalı bir ek ipucu olacaktır.
Dokümanları güncel tutmak çok zor
Evet, kesinlikle doğru. Birçok farklı yerde saklanan dokümantasyon içeriklerini güncel tutmak zordur. Geliştirici, içerikleri kaynak kodla birlikte tutarlı bir şekilde güncellemiyorsa, bayatlayacaktır. Bu nedenle, amacımız, mümkün olduğunca kod geliştirme sürecinin içine yerleşmiş bir dokümantasyon kurgusu yapmak olmalıdır. Doğru yapılırsa, dokümantasyon kolayca atlanabilecek bir "iş yükü" değil, programlamanın temel bir adımı olabilir.
Doküman yazmak geliştirme sürecini fazladan uzatıyor
Bu görüş, güncel tutulmasının zor olduğunu savunan düşünce ile aynı sorunlardan kaynaklanmaktadır. Dokümantasyon adımlarınız kod geliştirme süreciyle uyumlu değilse, gerekliliği sorgulanan bir sürü "ekstra" iş gibi görünecektir. Bu şekilde hisseden geliştiriciler genellikle “hıza” öncelik veren şirketlerde veya notunun bir parçası olmadığı akademik çevrede bulunmaktadır.
Dokümantasyonun çok uzun sürdüğü veya kodlama hızını yavaşlattığı pek doğru değildir. Bir hatayı düzeltmek için kodun neden böyle olduğunu anlamaya çalışırken ne kadar zaman kaybedebileceğimizi bilirsiniz. Muhtemelen, belirli bir kod parçasının neden eklendiğini unuttuğunuz, kaldırdığınız ve ardından sorunun ne olduğunu "yeniden keşfetmek" zorunda kaldığınız bazı hikayeleriniz de vardır. Sizce bu durumlarda o kısmın önceden yazılmış dokümantasyonu olsaydı size "hız" kazandırır mıydı?
Lütfen bu tarz olumsuz alışkanlıkları olanlardan olmayın.
Dokümantasyon, gelecekte zaman kazandırır.
Kodumuzu nasıl dokümante etmeliyiz?
Nereye ve Neden
Oluşturmak isteyeceğiniz birkaç tür dokümantasyon yeri ve sebebi vardır. Genellikle aşağıdaki gibi kategorilere ayrılabilir:
-
Satır içi yorumlar
-
En hızlı dokümantasyon tipi tahmin edebileceğiniz gibi satır içi yorumlardır.
-
Bunları kodumuzu oluştururken yazarız ve kodumuzun neden böyle göründüğüne ilişkin gelecekteki kendimize ipucları bırakırız.
-
Bu tür yorumlar; kodunuzda veya fonksiyonlarda neler olduğunu ve kodun ne yapmak istediğini açıklar.
-
Örneğin:
-
-
Başlık veya sınıf dokümantasyonları
- Bu tarzda otomatik dokümante etmede kullanılan çeşitli araçlar, rahat erişilebilir raporlar oluşturmada sıklıkla tercih edilir. Bu çalışmanın amacı özellikle ilgili sınıfa/fonksiyona ait detayların diğer yazılımcılara açıklanmasıdır.
- Örnek araçlar
-
Kullanım dokümantasyonu
- Gerçek kodların kapsamı dışında kalan kullanım dokümantasyonu biraz daha yüksek seviyeli yönergeleri içerir. Kodun ve kütüphanenin kullanımı ile ilgili eğitici içerikleri de barındırmalıdır. Bu belgeyi son kullanıcı dahil, diğer tüm yazılımcılar inceleyebileceği için dili ve içeriği ona göre tasarlanmalıdır.
- Örnek araçlar
Dokümantasyona nasıl teşvik edilebilir?
Doğru ve yardımcı araçlar kullanarak
Bu kısım belki de en can alıcı, en çokomelli, en önemli konu. Zaten şimdiye kadar önemsenmeyen, hep geri planda tutulan bir konuyu tekrardan su yüzüne çıkartıyoruz. Ekibin mümkün olduğunca az dirençle karşılaşarak dokümantasyona katkı sağlayacağı ne kadar araç varsa hepsinden faydalanmaya çalışın.
İlk zamanlarda koda yakın kısımlarda dokümantasyonu bitirmeye çalışmak, iyi alışkanlıkları pekiştirecektir.
Kendi kendinize, kendiniz için yaparak
Dokümantasyonun kendinize sağlayacağı faydaları düşünerek motivasyonunuzu arttırabilirsiniz. Bugün satır aralarına ekleyeceğiniz kısa, öz ve net bilgilendirmeler, yarın size zaman kazandıracaktır.
Ayrıca bir sistemi başarıyla ayağa kaldırdığınızda, geçtiğiniz adımları, yüklediğiniz ek paketleri, terminal geçmişinizi; hızlı bir düz metin veya markdown halinde kodlarınızın yanında tutabilirsiniz. AWS, GCP, k8s veya RPi, AGX gibi farklı ortamlar, kodlarınızı ayağa kaldırmada size hız kazandıracaktır.
Görev tanımı içinde yer alan destek ekibi kurarak
Kültür, standartları yeniden onaylayarak ve iyi uygulamaları takip edenleri ödüllendirerek yaratılır. Kodların stilini, kalitesini, çalışma sürekliliğini korumak destek ekibinin yetki ve sorumluluğundadır. Bu bakış açısı ile dokümantasyonun kalitesini korumak da onların görev tanımı içinde yer alabilir. Tabi unutmayalım ki destek ekibine de kodu yazan geliştiricilerin yardımcı olması gerekmektedir. Bu desteğin yine yardımcı araçlar ile sağlanması da önemlidir.
Özetleyip, maddelere dökecek olursak
- Okuma isteği oluşturacak, net dokümanlar yazalım.
- Dokümanlarımızı her zaman güncel tutalım.
- Projenin tüm yönlerini ele alan, kapsamlı dokümanlar yazalım.
- Hızlıca göz gezdirilerek bilgi sahibi olunabilecek içerikler ekleyelim.
- Projenin nasıl kullanılacağını anlatan örnekler sunalım.
- Kullanışlı olduğunu düşünüyorsanız tekrarlı içerikler sunalım.
- Dış unsurlar dahil herkesin rahatça katkıda bulunabilmesini sağlayalım.
- Gerekli gizlilik sınıfına göre bulunmasını kolaylaştıralım.