Kod Dokümantasyonu ve JavaDoc Üzerine – 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.

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