Kod Dokümantasyonu – I: API Dokümantasyonu

Yazılımda dokümantasyon devamlı konuşulan konulardandır. Nihayetinde dokümantasyon hararetli bir alandır, şiddetli taraftarlıklara konu olur ama muhtemelen en başarılı taraftarlık her zaman “dokümantasyon yapmamak”tır. Yani herkes bu konuyu farklı açılardan ele alır ama hala dokümantasyon yerinde sayar. Özellikle projelerin başında bu konuda belli kararlar alınsa ve uygulansa bile hararetin ilk arttığı dakikadan itibaren muhtemelen ilk terkedilen şey dokümantasyon olur.

Bu yazıda kodun dokümantasyonu üzerine bir şeyler yazmak istiyorum. Ama önce kod dokümantasyonundan ne anlıyoruz onu bir netleştirmemiş lazım. Kod dokümantasyonu öncelike ikiye ayrılır: Kodun API dokümantasyonu ve kodun iç dokümantasyonu. Bu yazıda ilkini ele alalım.

Kodun API dokümantasyonundan kastım, kodda var olan sınıf, arayüz, metot vb. yapıların “ne yaptıklarının” dokümantasyonudur. Buna kısaca arayüz dokümantasyonu (interface documentation) ya da daha bilinen haliyle API dokümantasyonu (API documentation) denir. API, malum Application Programming Interface’in kısaltmasıdır ve bir yazılımın sahip olduğu sınıf, arayüz, metot vb. yapıların dışarıdan görünene taraflarının tamamına denir. Dolayısıyla API’de kod yoktur, kodun tanımı vardır. API, bir yazılım sisteminin alt bileşenlerinin ne yaptığına odaklanır. Bu anlamda API kod değildir, kodun arayüzüdür ve “ne”liği vurgular, “nasıl”lık üzerine detay barındırmaz. Tam da bu yüzden kod dokümantasyonu derken, kodun içinde bulunduğu sınıf, metot vb. yapıların dokümantasyonu ile kodun içinde yapılan, iç dokümantasyonu ayırırız.

Kodu anlamak, doğrudan IDE üzerinde açılan kodlara bakarak elde edilemeyecek kadar karmaşık bir iştir. API kültürünün olmadığı yazılım ortamlarında yapılan, kodu IDE’de açıp, sınıflar ve metotlar arasında gezinerek, kodu takip ederek, gerekirse debugger kullanarak, kodun detaylarını anlamaya çalışmaktır. Bu ise iğneyle kuyu kazmaktan farksızdır ve çok yanlışa sebep olur. Kodu anlama, bir metot için örneğin, “bu nasıl çalışıyor?” sorusuyla başlamaz, “bu ne yapıyor” sorusuyla başlar. Ne yaptığını anlamadan nasıl yaptığına girişmek ya da nasıl yaptığını anlayarak ne yaptığını çıkarmak, metodolojik olarak zaten yanlış yöntemlerdir, çünkü detayda kaybolursunuz, bu yüzden de çok yorucudur ve aşırı zaman tüketmenize sebep olur. Kod ile ilgili çalışmalarımızın ezici tarafının var olan kodu değiştirmek olduğu gerçeğini düşünürseniz, kodun ne yaptığını anlamanın ne kadar önemli olduğunu farkedersiniz.

API dokümantasyonu sadece yazılım geliştirenler açısından değil, bir yazılımı dışarıya geliştirtenler açısından da hayati öneme sahiptir. Yani bir kurum dış bir kaynakla, kendisine yazılım sistemi geliştirmesi için anlaşıp,  sonrasında geliştirilen bu sistemi içeriye alıp BT biriminin sorumluluğuna vermeyi düşünüyorsa, projeyi geliştiren takımdan sadece kod değil, kodun beraberinde API dokümantasyonunu da alması gereklidir. Kodun geliştirilmesi için tonla para harcayıp, sonra heyula hale gelmiş kod tabanını hiç bir API dokümantasyonu olmadan içeriye alıp yazılımcıların önüne yığmak bence hayret verici derecede problemli ve cesur bir iştir. Bunu yapan yazılım yöneticilerini anlamadığım gibi bu duruma karşı bir eleştiride bulunmayan, aslında olup biteni kavramamış, bu yüzden de itiraz edemeyen yazılımcılara da hep hayretle bakmışımdır. (Gerçi, itiraz edilse ne değişir diyebilirsiniz ama ben daha çok “problem olmaz, kodu devralırız” diye cesurca ortaya çıkan yazılımcıları kastediyorum.) Prensip şu olmalı: Kod varsa APIsinin dokümantasyonu da olmalı. Bu durum geliştirenler açısından da geliştirtenler açısından da devir alanlar açısından da böyledir. Çünkü kod sadece çalışıyorsa, anlaşılamıyorsa, değiştirilmekte zorlanılıyorsa, kandırıldınız demektir. Çünkü kodun çalışması, zaten olmazsa olmaz özelliğidir. Satın almayı planladığınız bir aracın çalışmasından farklı değildir. Eğer aracınızın lastiklerini değiştirmek çok zor ve  2500 TL’ye mal oluyor ve daha da kötüsü her gün değiştirmek zorunda kalıyorsanız, aracın nasıl çalıştığıyla ilgilenmezsiniz. Durum bence yazılım açısından bu kadar vahimdir.

Bence aynı durum kurumundaki BT biriminde yazılım geliştiren ya da yazılım evleri için de geçerlidir, hatta daha vahimdir. Bu amaçla yazılım geliştiren ya da geliştirten her yer ve herkes kullandıkları teknolojide var olan API dokümantasyonu yapmak için gerekli yapıları öğrenmeli ve uygulamaya koymalıdır.

Kodun API dokümantasyonu noktasında Java severlerin kullanabileceği JavaDoc isimli nefis bir yapı ve araç var. JavaDoc, Java ile yazılan kodların API dokümantasyonunu yakmak üzere oluşturulmuş bir standart ve bir araç. JavaDoc’un nasıl yazılacağı ve üretileceği ile ilgili daha önce burada ve burada iki yazı yazmış ve örnek üzerinden de açıklamıştım. Artık hemen her dilde API dokümantasyonuna yönelik standartlar ve araçlar oluşturuluyor. Bu anlamda eskilerden daha şanslıyız, yeter ki gerekliliğine inanalım ve vakit ayıralım.

Bir sonraki yazıda kodun iç dokümantasyonunu ele almak üzere.

Toplam görüntülenme sayısı: 2701