Kod Dokümantasyonu ve JavaDoc Üzerine – II

Bir önceki yazıda JavaDoc açıklamalarının nasıl yazılacağından ve javadoc aracını kullanarak API dokümanının nasıl üretileceğinden bahsetmiştik. Bu yazıda bu konuyu sonlandıralım.

Kodunuzu bu şekilde dokümante etmeniz, kodunuzun APIsini çıkarmak anlamına gelir. API dokümantasyonu, kodun iç çalışma şeklinin açıklanması anlamına gelmez. Aksine, kodunuzu dışarıdan kullanacak kişi için, kodun iç yapısına girmeden sadece arayüz seviyesinde doküman sağlar.

Sağlıklı yazılan kodlar için aslında çoğu zaman API dokümantasyonu yeterlidir. Eğer kodunuzu karmaşık değil de basit yazarsanız, uzun kodlarınızı farklı metotlara ve sınıflara bölerseniz, metotlarınıza olabildiğince az parametre geçerseniz,  hem metotlarınız hem de sınıflarınız son derece yalın, kısa ve anlaşılır olacaktır. Bu sayede JavaDoc, kodunuzun anlaşılması için yeterli olacaktır. Aksine metotlarınızı ve sınıflarınızı uzun ve karmaşık tutarsanız şu iki durumdan birisini yapmak zorunda kalırsınız: Ya JavaDoc dokümantasyonunda kodunuzun iç çalışması ile ilgili detay verirsiniz ki bu kesinlikle istenen bir şey değildir, ya da kodunuzda JavaDoc dışında “//” ya da “/*   */” ile API’de gözükmeyecek açıklamalar yazarsınız.  Kodunuzu ne kadar yalın, basit ve anlaşılır kurgulayıp yazarsanız JavaDoc dışında o kadar az iç dokümantasyon yaparsınız. Yapacağınız JavaDoc açıklamaları hem müşterileriniz hem de sizin kendiniz için yeterli olur.

Yukarıdaki tartışmadan kodunuz için API dışında bir iç açıklama yapmayın demiyorum. Her halukarda zaman zaman “//” ya da “/*   */” ile açıklama yapmak zorunda kalabiliriz. Ama unutmayın ki ne kadar basit ve kısa kod yazarsanız bu türden açıklamalara o kadar az ihtiyaç duyarsınız. Yani kodunuz, var olduğu haliyle kendini yeterince açıklıyor demektir.

JavaDoc o kadar önemli ki, örneğin  bir framework kullanmaya giriştiğimizde ya da bir component satın aldığımızda/indirdiğimizde dokümantasyon olarak ilk bakacağımız şey API dokümantasyonu olmalıdır. Bir yazılım evi ile bir proje için anlaştığımızda, bize teslim edilecek kod yanında JavaDoc’un da hazırlanması gerektiğini anlaşmada belirtmemiz gereklidir. Kodu devralırken, kod ile birlikte API dokümantasyonunu devralmalı, eğer bir eğitim de söz konusu olacaksa, API de bu eğitimin ciddi bir parçası olmalıdır.

Eğer yazılım geliştiriyorsanız, hem kendiniz hem de arkadaşlarınız için JavaDoc yazmalısınız. Bu şekilde sizin kafanızdaki o yapıyla ilgili bilginin, rahatlıkla başkaları tarafından hızlıca kazanılmasını sağlamış olursunuz. Eğer hic bir şekilde dokümante edilmemiş bir kod devralmışsanız, kodun her dokunduğunuz yerine JavaDoc yazarak, biriktirmeye başladığınız bilginizi, kalıcı ve paylaşılabilir hale getiriyorsunuz demektir. Bir müddet sonra tüm kodun dokümante edildiğini gördüğünüzde çok güzel bir iş yapmış olduğunuzu ve bakımı anlama yönünden kolaylaştırdığınızı farkedeceksiniz.

Peki JavaDoc’u kim kullanıyor dersiniz? İşin açıkçası Javacılar, var olan JavaDocları bile düzenli bir şekilde kullanmıyorlar, bırakın yazmayı. Halbuki diyelim ki Spring gibi bir frameworkü öğreniyorsunuz, JavaDoc’u elinizin altında olmalı. Hibernate’in yeni versiyonunu indirdiniz, JavaDoc’unu da indirip, bütün dokümantasyonlarınızı koyduğunuz yere koyun örneğin ve yerini de tarayıcınıza kısa yol olarak kaydedin öyle ki tarayıcınızda Java diye bir folder olsun ve altında her türlü Java yapısının API’lerine kısa yollar olsun. Tabi ki en temel olması gereken kısa yollar ise Java SE ve Java EE API’leri icin olmalı. Uzun lafın kısası, makinanızda kendisiyle geliştirme yaptığınız her Java yapısı için, framework olsun component olsun, utility vb. olsun, elinizin altında o yapıların JavaDoc’larını bulundurmalısınız.

Ben eğitim ya da danışmalık verdiğim zamanlar, özellikle ele alacağımız konularla ilgili APIleri muhakkak katılımcılara dağıtıyor ve tarayıcılarından hızlıca ulaşılır hale getirmelerini rica ediyorum. İlgili APIleri webden nasıl indireceklerini açıklıyorum. Zira APIden haberdar olmadan geliştirme yapan o kadar çok Javacıyla karşılaşıyorum ki her seferinde böyle güzel bir araç varken neden körleme ve son derece verimsiz bir kod geliştirme yöntemine sahibiz diye düşünmeden edemiyorum.

Çok sık karşılaştığım sahne şu: Geliştirme ortamının (IDE) editöründe bir referans yazılıp sonuna “.” basılır, sonra da IDE’nin çıkardığı listeden bir metot seçilir ve derlenip çalıştırılır. Eğer bir problem çıkmazsa ne ala. Yok problem çıkarsa seçilen metot silinir ve tekrar “.” konup çıkan listeden bir başka metot seçilir. Eğer ilgili nesnenin APIsini biliyor da sadece hatırlamak için bu yöntemi kullanıyorsak bir problem yok. Ama nesnenin ne işe yaradığını bilmiyorsak, APIsine bakmak yerine bu şekilde hızlıca doğru metodu denk getirmeye çalışıyorsak işimiz vahim demektir. Şahsen ben böyle kod geliştiren bir developerın koduna güvenmem.

Bir kere JavaDoc’u kullanın ve yarattığı etkiyi görün, bence bir daha vazgeçemeyeceksiniz. Aslında çoğu zaman sadece bilmediğimiz, tecrübe etmediğimiz için korkup kullanmıyoruz. Unutmayın, kullandıgımız Java SE, ME, EE ve her türlü Spring, Hibernate vb. frameworklerin API dokümanları, sadece ve sadece bu yapıları geliştiren developerların, geliştirme esnasında yazdıkları açıklamalardan oluşuyor. Çünkü kod dokümantasyonu olsa olsa ancak kodu yazarken yapılabilir.

Bence Google programcılığını engellemenin en temel yolu, Javacılar için API kullanımını vazgeçilmez bir alışkanlık haline getirmekten geçer.

Bol JavaDoclu günler dilerim 🙂

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