Search Results for: kod dokümantasyonu

Kod Dokümantasyonu – II: İç Dokümantasyon

Yazılım Mühendisliği

Bir önceki yazıda kod dokümantasyonu ele aldık ve bu konunun iki alt başlığı olduğunu söyleyip kodun APIsinin dokümante edilmesinin ne anlama geldiğinden ve gerekliliğinden bahsettik. Dolayısıyla kod dokümantasyonundan bahsettiğimizde doğrudan kodun içine yazılan ve genellikle “iç dokümantasyon” (internal documentation) olarak adlandırılan ve Java vb. dillerde çoğunlukla “//” ile “comment” haline getirilen açıklama ifadelerini anlamamalıyız. API dokümantasyonu, kodu anlaşılır kılmak için yapılacak en önemli açıklamadır.

Öte taraftan, iç dokümantasyona geldiğimizde bunun API dokümantasyonu kısmından daha karmaşık olduğunu söyleyebiliriz. Sık sık duyuyorum, “hocam koda ne kadar dokümantasyon yazmalıyız?” şeklinde sorular. Hoş, bunu soranlar belli ki henüz öğrenci olan arkadaşlar ve kariyerlerinde hiç kod dokümantasyonu yazmama ihtimalinin yüksek olduğunu bilmiyorlar tabi 🙁

Açıkçası koda iç dokümantasyon yani açıklama (comment) yazmak, prensip olarak iyidir. İnsanların niyet olarak kodlarını anlaşılır kılmak için “dokümantasyon yapayım” diye düşünmeleri son derece güzel bir şeydir. Lakin kodu anlaşılır kılmanın, dokümantasyon yazmaktan daha önce gelen bir yolu vardır: kodu anlaşılır yazmak. Kodu karmaşık yazıp, özensiz, çala-kalem yazıp, sonra dokümantasyon ile anlaşılır kılmak, kötü kodu açıklamalar yoluyla tamir etmeye çalışmaktır. Bir inşaat ustası olarak duvarı üflesen yıkılacak şekilde kötü örüp sonra çok iyi bir sıva ile bütün bu durumu kapatmak gibi. (Biliyorum iyi bir örnek olmadı, sıvasız duvar olmaz ama dokümantasyonsuz kod olur 🙂  ) Ya da kendini ifade etmekte devamlı zorluk yaşayan, dili düzgün kullanamayan birisinin, düşüncelerini anlatmak için devamlı açıklamalar yapmasına benzer bu durum, konuştuka anlaşılmaz hale gelir. Bu yüzden aslolan dokümantasyon yazmak değildir, aslolan anlaşılır kod yazmaktır öyle ki açıklamaya gerek kalmasın. Buna “self-descriptive” ya da “self-documenting” kod da denir.

Eski kitaplarda örneğin 70lerin ve 80lerin kitaplarında kod ile dokümantasyonu arasındaki oranın 1/2 olmasından bahsedilirdi. Bir satır koda iki satır dokümantasyon! Bu açıkçası o zamanki ortamların ve dillerin yapısıyla, sahip olunan kültürden kaynaklanan bir durumdu. Örneğin bellek problemi çok kısa isimler vermeye zorluyordu yazılımcıları. Ama artık öyle değil, Allah’ın mekanı geniş, istediğiniz kadar uzun isimler yazabilirisiniz yeter ki anlamlı olsun.

Eğer kodunuzun yazdığınız haliyle anlaşılmasının zor olduğunu düşünüyorsanız, lütfen ona dokümantasyon yazmayın. Dokümantasyonu kodunu yazdığınız işin tabiatından kaynaklanan, örneğin karmaşık bir algoritmada olduğu gibi, anlama zorlukları için yazın. Ya da beklenenin dışında bir durum söz konusudur onu belirtin. “Ama hocam yaptığımız iş karmaşık ve kodu uzun tutuyor” diyorsanız, karmaşıklığı ile ilgili “bu durum olabilecek en basit hal midir? Daha da basitleştirilemez mi?”, uzun tutması için de “bir kez daha düşünün” bu kadar uzun olmalı mı? “Uzun olan işi atomik alt parçalara böldünüz mü?” diye sorarım. Dolayısıyla eğer kodunuzun yazdığınız haliyle anlaşılmasının zor olduğunu düşünüyorsanız, onu refactor edin, elden geçirin ya da tekrar yazın. İsimlerinizi kontrol edin, satırlarınızı atomik, tek bir işi yapacak hale getirin, zincirleme kod çağrılarını (a.f().g().u() gibi) açın, bol yerel değişken kullanın, metotlarınızın içinde atomik olan kısımları “{}” ile bloklayın ki o kısmı yalıtın ve nihayetinde kodunuzu bölüp parçalayın. Daha önce yazmıştım, kod eklenerek değil çıkartılarak büyür. Kodu anlaşılır kılmanın en temel iki yolu, iyi isimlendirme ve kısa kod yazmadır. Bunlara dikkat ederseniz, muhtemelen yazmak zorunda kalacağınız açıklamalar çok azalacaktır.

Bu konuda Brian W. Kernighan ve  P. J. Plaugher’ın “Don’t comment bad code—rewrite it.” yani “Kötü kodu açıklama – tekrar yaz.” şeklindeki sözlerini hatırlamak gerekir.

Uncle Bob’a atfedilen “Her açıklama bir özürdür.” sözü bakın şöyle bir cümlede geçiyor:

“A comment is an apology for not choosing a more clear name, or a more reasonable set of parameters, or for the failure to use explanatory variables and explanatory functions. Apologies for making the code unmaintainable, apologies for not using well-known algorithms, apologies for writing ‘clever’ code, apologies for not having a good version control system, apologies for not having finished the job of writing the code, or for leaving vulnerabilities or flaws in the code, apologies for hand-optimizing C code in ugly ways…”

Yani

“Her açıklama, daha açık bir isim ya da daha makul bir parametre seti seçilmediği ya da daha açıklayıcı değişkenler ve fonksiyonlar kullanılmadığı için bir özürdür. Kodu bakım yapılamaz kıldığı için özür, iyi bilinen algoritmalar kullanmadığı için özür, “zekice” kod yazdığı için özür, iyi bir versiyon yönetim sistemi kullanmadığı için özür, kod yazma işini bitirmediği için özür ya da kodda sıkıntılı veya hatalı kısımlar için özür, elle ve çirkin şekilde yapılmış optimize C kodu için özür… “

Peki hiç mi iç dokümantasyon yapılmamalı? Tabi ki hayır. Ben her halükarda API dokümantasyonunun yapılması gerektiğini düşünüyorum. Metot istendiği kadar basit olsun, bir cümleyle de olsa API açıklaması konmalı ki örneğin JavaDoc ile API dokümantasyonu ürettiğimizde her şey eksiksiz olsun.

Öte taraftan gerek API gerek ise kod içi dokümantasyonun kaçınılmaz olduğu durumlardan birisi ise devralınmış koddur. Devralınmış ve kötü ve karmaşık yazılmış koda değişiklik yaparken anladığınızı koda gerek API gerek ise içerideki satırlar düzeyinde açıklama olarak yazmanız o kodu gittikçe çok daha anlaşılır hale getirecek, takımdaki bilgi birikimini paylaşarak hızlandıracaktır. Ben, dışarıda geliştirildikten sonra içerideki geliştirme takımının önüne konan koda, devralan takımdaki yazılımcıların, dokundukları her noktaya anladıklarını kaydetmemelerini de anlamış değilim. Böyle hallerde herkes her yeri kendisince tekrar tekrar anlamaya çalışıyor demektir.

Uzun lafın kısası, açıklamaya yazma, açık kod yaz, kendini açıkça ifade eden kod yaz. Bu anlamda koduna bol bol açıklama yazandan ziyade, temiz ve açık kod yazan taktir edilir.

Koda yazılacak API ya da iç dokümantasyon için Robert Martin ya da Uncle Bob’ın “Clean Code“, P. Goodliffe’nin “Code Craft” ve Steve McConnell’in “Code Complete” kitaplarının ilgili kısımlarını okumanızı tavsiye ederim.

Açıklama gerektirmeyen, açık ve seçik kod yazmak ve devralmak ümidiyle 🙂

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

Kod Dokümantasyonu – I: API Dokümantasyonu

Yazılım Mühendisliği

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ı: 2553

Kod Dokümantasyonu ve JavaDoc Üzerine – II

Java, Yazılım Mühendisliği ,

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ı: 2112

Kod Dokümantasyonu ve JavaDoc Üzerine – I

Java, Yazılım Mühendisliği , ,

Soyut ve karmaşık olan yapısından dolayı yazılım geliştirme sürecindeki en temel problem anlama-anlaşma problemidir. Bu problemi gidermek için ne yapılsa yeridir. Dokümantasyon da bu problemi gidermenin en temel yollarından birisidir. Tabi olarak yazılım geliştirme sürecinin farklı kısımlarının farklı türde dokümantasyona ihtiyaç vardır. Analiz sürecindeki dokümantasyon ile mimari çalışmalardaki ya da kodlamadaki dokümantasyonun farklı içerikte ve formatta olması kaçınılmazdır.

Sanırım tüm dünyada yazılım dokümantasyonu pek sevilen ve özen gösterilen bir konu değildir. Hele konu kod dokümantasyonu olunca, hiç bir yazılım geliştiricinin bunu severek yaptığını düşünmüyorum. Aslında kesinlikle kod yazmak kadar zevkli olmayan bu tür çalışmaların, zekasının sınırlarında gezmekten haz alan geliştiriciler için çok çekici olmadığının da farkındayım. Ama bu kadar karmaşık ve soyut yapıların anlaşılmasını sağlamak ve bu anlaşılmayı sürdürebilmek, kalıcı kılmak için, her şeyden önce, kendi çalışmamızı kolaylaştırmak, kendimize yardım etmek için kodumuzu dokümante etmemiz lazım.

Java, kodun API dokümantasyonu için ta başından bu yana JavaDoc isimli bir yapıya sahiptir. JavaDoc hem kod dokümantasyonu hem de API dokümantasyonu için nefis bir araçtır. Sonrasında çıkan C# ya da Scala gibi diller de benzer yapılar oluşturuldu zaten.

JavaDoc, kod için API dokümantasyonu yazmak için bize bir format sunar. Bu formatta HTML etiketleri kullanılabileceği gibi JavaDoc’un kendine has “@author” ya da “@see” gibi etiketleri de kullanılabilir.

JavaDoc dokümantasyonunu, class, interface ya da enum tiplerinden önce, nesne ve sınıf değişkenlerinden önce ve constructorlar dahil olmak üzere metotlardan önce, /** */ formatında yazılır. Yani JavaDoc yorumlarınız, “/**” ile başlamalı ve “*/” ile bitmelidir. JavaDoc yazarken HTML kullanabilirsiniz çünkü zaten nihayetinde üretilecek olan doküman bir HTML dokümanıdır.

Örneğin Bulp isimli bir sınıfı, bu sınıfın tanımlandığı yerde JavaDoc ile şöyle açıklayabiliriz.

package org.javaturk.oop.ch08;

/**
*  A <code>Bulp</code> is a bulp.
 * This class simulates a bulp. It has a default constructor that creates a bulp
 * with a max luminescence of 60 and another constructor that creates a bulp with
 * specified max luminescence.
 * <p>
 * This class has methods to turn on and turn off the bulp and to increase and 
 * to decrease the current luminescence of the bulp.
 *
 * @author Akin Kaldiroglu
 * @version 1.3.7
 * @see <a href="http://www.javaturk.org">JavaTurk.org</a>
 * @since 1.2
 */
public class Bulp{
    
	public static final int STANDARD_MAX_LUMINESCENCE = 60;
    String name;
    private int currentLuminescence;
    protected int maxLuminescence;
    
    /** Creates a new Bulp object with standard luminescence. */
    public Bulp() {
        maxLuminescence = STANDARD_MAX_LUMINESCENCE;
        currentLuminescence = 0;
        System.out.println("A bulb with max luminescence of " + maxLuminescence + " created.");
    }
    
    /** 
     * Creates a new Bulp object with specified max luminescence
     * @param maxLuminescenceValue Max luminescence of the bulp
     */
    public Bulp(int maxLuminescenceValue) {
        maxLuminescence = maxLuminescenceValue;
        currentLuminescence = 0;
        name = "bulb" + new String((new Integer(maxLuminescence)).toString());
        System.out.println("A bulb " + name + " with max luminescence of " + maxLuminescence + " created.");
    }
    ...
}

Yukarıdaki örnekte Bulp sınıfının JavaDoc ile dokümante edilmiş hali var. Görüldüğü gibi dört farklı JavaDoc etiketi kullanılmış durumda. Ayrıca Bulp’ın içinde tanımlanmış üç tane de değişken var. Bu üç değişken ise, JavaDoc’un bazı özelliklerini göstermek üzere, farklı erişim seviyelerinde tutulmuşlardır.

Aşağıda Bulp sınıfının metotlarının JavaDoc ile dokümante edilmiş hali görülmektedir:

...
    
    /** 
     * Sets max luminescence to specified value
     * @param value Specified max luminescence  
     * @exception IllegalArgumentException in case of passing non-positive argument.
     */
    public void setMaxLuminescence(int value) throws IllegalArgumentException{
    	if(value <= 0)
    		throw new IllegalArgumentException("Luminescence value passed must be greater than zero: " + value);
        maxLuminescence = value;
    }
    
    /** 
     * Gets max luminescence of the bulp.
     * @return max luminescence.
     */
    public int getMaxLuminescence(){
        return maxLuminescence;
    }
    
    /** 
     * Turns on the bulp.
     * Curent luminescence is set to max luminescence.
     */
    public void on(){
        currentLuminescence = maxLuminescence;
        System.out.println("Bulb  " + this.name + " is on now");
    }
    
    /** 
     * Turns off the bulp.
     * Curent luminescence is set to 0.
     */
    public void off(){
        currentLuminescence = 0;
        System.out.println("Bulp  " + this.name + " off now");
    }
    
    /** Just brightens the bulp. */
    public void brighten(){
        System.out.println("Bulb  " + this.name + " is brighter now");
    }
    
    /** 
     * Brightens the bulp to specified value.
     * @param value New luminescence of the bulp.
     * @exception IllegalArgumentException in case of passing non-positive argument.
     */
    public void brighten(int value) throws IllegalArgumentException{
    	if(value <= 0)
    		throw new IllegalArgumentException("Luminescence value passed must be greater than zero: " + value);
    	
        if(currentLuminescence < value){
            if(value <= maxLuminescence){
                currentLuminescence = value;
                System.out.println("Luminescence of " + this.name + " is increased to " + currentLuminescence);
            }
            else{
                System.out.println("Max luminescence of " + this.name + " is " + maxLuminescence);
            }
        }
        else{
            System.out.println("Do you want to make " + this.name + " brighter or dimmer?");
            System.out.println("Current luminescence of " + this.name + " is " + currentLuminescence);
            System.out.println("You tried to brighten it to " + value);
        }
    }
    
    /** Just dims the bulp. */
    public void dim(){
        System.out.println("Bulb  " + this.name + " is dimmer now");
    }
    
    /** 
     * Dims the bulp to specified value.
     * @param value New luminescence of the bulp
     */
    public void dim(int value) throws IllegalArgumentException{
    	if(value <= 0)
    		throw new IllegalArgumentException("Luminescence value passed must be greater than zero.");
    	
        if(currentLuminescence > value){
            if(value >= 0){
                currentLuminescence = value;
                System.out.println("Luminescence of " + this.name + " is decreased to " + currentLuminescence);
            }
            else{
                System.out.println("Don't be that silly! I am just a bulb not a black hole");
            }
        }
        else{
            System.out.println("Do you want to make " + this.name + " brighter or dimmer?");
            System.out.println("Current luminescence of " + this.name + " is " + currentLuminescence);
            System.out.println("You tried to dim it to " + value);
        }
    }  
}

Burada da metotlara geçılen parametrelerin “@param”, döndürülen değerlerin “@return” ve fırlatılan sıra dışı durumların ise “@exception” etiketleriyle nasıl dokümante edildiği görülmektedir.

Bu şekilde JavaDoc ile dokümante edilmiş olan kodunuzu, JDK ile birlikte gelen javadoc aracıyla HTML dokümantasyonu haline getirebilirsiniz. Bunun için yapmanız gereken java kaynak kodunu ya da class bytecodeunu kullanmaktır. Bunun için aşağıdaki gibi bir komut satırını kullanabilirsiniz:

javadoc -d doc Bulp.java

Bu komut ile Bulp.java dosyasında var olan Bulp sınıfının APIsini “doc” isimli bir dosyaya çıkarabilirsiniz. Bu durumda elde edilen API dokümanı şöyledir:

Bulp sınıfının APIsi.

Bulp sınıfının APIsi.

 

Oluşturulan bu nefis doküman, sizin kodunuzu yazarken girdiğiniz JavaDoc formatına uygun açıklamalardan oluşturulmuştur. Bu dokümanda örneğin sadece public ve protected olarak belirtilen alanlar görünmektedir. Benzer şekilde version ve author alanları da görünmemektedir. Bu alanların da görülmesini sağlamak için javadoc aracını çalıştırırken “-author” gibi ilgili flag değerlerini de geçmeniz gereklidir.

Oracle’in sayfalarında, burada ve burada JavaDoc kullanmak için nasıl açıklama yazılabileceği detaylıca anlatılıyor. Burada da JavaDoc’un resmi sayfası var.

Bu konuya bir sonraki yazıda devam edelim.

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

1 2 3