Java Yorumları: Tek Satırlık, Çok Satırlık ve Javadoc

Yorumlar Ne İşe Yarar

Yorum, kaynak kodunuzda Java derleyicisinin tamamen yok saydığı metindir. Asla çalışan programın bir parçası olmaz; yalnızca kodu okuyan insanlar için vardır. Yorumları, bir şeyin neden belirli bir şekilde yapıldığını açıklamak, hatırlatmalar bırakmak ya da kodu silmeden geçici olarak devre dışı bırakmak için kullanırsınız.

Java'da üç tür yorum vardır: tek satırlık (//), çok satırlık blok yorumları (/* */) ve Javadoc belge yorumları (/** */). Hepsi aynı temel işi yapar (derleme sırasında yok sayılır) ama her birine farklı durumlarda başvurursunuz.

Tek Satırlık Yorumlar

İki eğik çizgi (//) geçerli satırın sonuna kadar süren bir yorum başlatır. Derleyici // işaretinden satır sonuna kadar her şeyi atlar.

public class Main {
    public static void main(String[] args) {
        // Konsola bir selamlama yazdır
        System.out.println("Hello, Java!");

        int score = 90; // bir yorum kodun ardından da yer alabilir
        System.out.println(score);
    }
}

İkinci yorumun gerçek kodla aynı satırı paylaştığına dikkat edin. // işaretinden önceki her şey yine çalışır; yalnızca ondan sonraki kısım yok sayılır. Bu, kısa notlar için en yaygın yorum biçimidir.

Çok Satırlık Blok Yorumları

Notunuz birkaç satıra yayıldığında, her satırın önüne // koymaktansa blok yorumu daha temiz olur. Blok yorumu /* ile başlar ve */ ile biter. İkisinin arasındaki her şey (kaç satır olursa olsun) yok sayılır.

public class Main {
    public static void main(String[] args) {
        /*
         * Bu program bir blok yorumu gösterir.
         * Her satırın başındaki yıldızlar yalnızca okunabilirlik
         * için bir gelenektir; zorunlu değildir.
         */
        System.out.println("Block comments are handy.");
    }
}

Sol kenar boyunca hizalanmış * karakterleri bir stil geleneğidir, kural değil. Gerçekten önemli olan tek şeyler açılış /* ve kapanış */ işaretleridir.

Kodu Yorum Satırına Almak

Yorumlar, deneme yaparken kodu silmeden devre dışı bırakmanın standart yoludur. Tek satır için //, birkaç satırı aynı anda kapatmak için bir blok yorumu kullanın.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

Çalıştırın; yalnızca iki "runs" satırının yazdırıldığını göreceksiniz. Yorum satırına alınmış println çağrıları derleyici için görünmezdir.

Yaygın bir tuzak: blok yorumları iç içe geçmez. Önünde kaç tane /* olursa olsun, ilk */ yorumu kapatır. Bu yüzden bir /* ... */ bloğunu başka bir /* ... */ bloğunun içine saramazsınız; içteki */ tüm yorumu sonlandırır ve geri kalanı söz dizimi hatasına dönüşür. Zaten blok yorumları içeren bir bölgeyi devre dışı bırakmanız gerekiyorsa, her satırda // kullanın (çoğu düzenleyici bunu tek bir klavye kısayoluyla yapar).

Javadoc Belge Yorumları

Javadoc yorumu bir blok yorumuna benzer ama /** ile başlar; iki yıldız. Bir sınıfı, metodu veya alanı belgelemek için tasarlanmıştır ve tanımladığı şeyin hemen üstünde yer alır. javadoc aracı bunları gezilebilir HTML API belgelerine dönüştürür ve IDE'ler bunları imleç üzerine gelindiğinde ipucu olarak gösterir.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

@param, @return ve @throws etiketleri aracın anladığı yapılandırılmış alanlardır. Derleyici için bu hâlâ yok sayılan bir yorumdur; değeri tamamen ürettiği belgelerde ve IDE'nin diğer geliştiricilere (ve altı ay sonra size) verdiği ipuçlarındadır.

İyi Yorumlar ve Gürültü

Bir yorum, kodun kendi başına söyleyemeyeceği bir şeyi açıklamalıdır. Yalnızca kodun yaptığını tekrarlayan yorumlar karmaşa yaratır ve kod değiştikçe güncelliğini yitirme eğilimindedir.

// Kötü: kodun açıkça yaptığı şeyi yalnızca tekrarlıyor
int i = i + 1; // i'ye bir ekle

// Daha iyi: kodun gösteremediği nedeni açıklıyor
retries++; // geri çekil ve yeniden dene; API saniyede 5 isteğe sınırlandırılmış

Kodu açık adlar ve iyi bir yapı aracılığıyla okunabilir kılmaya çalışın ve yorumları neden için saklayın: amaç, ödünleşimler, uç durumlar ve bağlam bağlantıları. Kafa karıştıran bir satırı açıklamak için yorum yazdığınızı fark ederseniz, bu çoğu zaman bir değişkeni yeniden adlandırmanız veya bir metot çıkarmanız gerektiğinin işaretidir.

Sonraki: Değişkenler

Artık kodunuza notlar ekleyebildiğinize göre, sıradaki yapı taşı içinde veri saklamaktır. Sonraki sayfa değişkenleri ele alıyor: bunları nasıl tanımlayacağınızı, tuttukları türleri ve Java'nın statik tip kontrolü yaptığı için dayattığı kuralları.