C'de Yorumlar: // ve /* */ Anlatılıyor

Yorum, derleyicinin çöpe attığı metindir. Yalnızca kodu daha sonra okuyacak insanlar için vardır ve bunlardan biri genellikle sizsiniz. C iki biçim sunar ve her birinin ne zaman doğru araç olduğunu bilmek yaklaşık iki dakika sürer.

İki Biçim

#include <stdio.h>

int main(void) {
    // Tek satirlik yorum: //'den satir sonuna kadar her sey.

    /* Bir blok yorum.
       Istediginiz kadar satira yayilabilir
       ve yalnizca kapanis isaretinde biter. */

    printf("Yorumlar ciktiya asla ulasmaz.\n");  // kodun ardina da gelebilir
    return 0;
}

Çalıştırın: çıktı tek satırdır. Her iki yorum da derleyici programı ayrıştırmadan önce silindi - çalışma zamanında hiçbir maliyetleri yoktur ve çalıştırılabilir dosyaya hiçbir şey eklemezler.

// fiziksel satırın sonuna kadar sürer. O satırda ardından hiçbir şey gelemez, dolayısıyla bu göründüğü gibi çalışmaz:

int x = 5;  // x'i beşe ayarla  int y = 6;   /* y hiç bildirilmedi */

/* ... */ nerede olursa olsun ilk */ işaretinde biter. Satır ortasında başlayıp bitebilir ki bu zaman zaman işe yarar:

int total = price /* vergi öncesi */ + shipping;

Neden İki Biçim Var

/* */, 1972'den, özgün C'dendir. // C++'tan geldi ve C'ye resmen ancak C99'da eklendi. Bu geçmiş, eski kodu okurken fark edeceğiniz bir şeyi açıklar: C89'a taşınabilir olacak şekilde yazılmış kütüphaneler tek satırlık yorumlar için bile /* */ kullanır, çünkü // hâlâ destekledikleri eski araç zincirlerinde derlenmezdi.

Bugün kullanma ihtimaliniz olan her derleyici ikisini de kabul eder. Sıradan notlar için //, bir yorum gerçekten satırlara yayıldığında /* */ kullanın. Çok eski bir gömülü derleyiciyi hedefliyorsanız //'ye güvenmeden önce kontrol edin.

Yorumlar İç İçe Geçemez

Tek gerçek tuzak budur:

/* Bu bölümü şimdilik devre dışı bırak
   int a = compute();
   /* klasik yardımcı - gözünüz üstünde olsun */
   int b = a * 2;
*/

Blok yorum ilk */ işaretinde, yani 3. satırdakinde biter. 4 ve 5. satırlar o zaman yine canlı koddur ve 6. satırdaki sondaki */ bir söz dizimi hatasıdır. Derleyicinin mesajı son satırı gösterir ve sebep konusunda tamamen faydasızdır.

Çözüm, iç içe geçmeyi gerçekten halleden ön işlemciyi kullanmaktır:

#if 0
    int a = compute();
    /* klasik yardımcı - gözünüz üstünde olsun */
    int b = a * 2;
#endif

#if 0 asla doğru olmaz, dolayısıyla ön işlemci, derleyici görmeden önce #endif'e kadar olan her şeyi siler. İçerideki yorumlardan, tırnaklardan ve diğer #if bloklarından etkilenmez ve temizlik yaparken aramak kolaydır.

Hata Ayıklarken Kodu Yorum Satırına Almak

Bir satırı geçici olarak kaldırmak, yorumların en yaygın günlük kullanımıdır. Bir program yanlış davrandığında her seferinde bir deyimi devre dışı bırakmak size hangisinin önemli olduğunu söyler.

#include <stdio.h>

int main(void) {
    int total = 0;

    for (int i = 1; i <= 5; i++) {
        total += i;
        // printf("adim %d: toplam = %d\n", i, total);  /* izlemek icin acin */
    }

    printf("Son toplam: %d\n", total);
    return 0;
}

printf'i yorumdan çıkarıp döngünün cevabını nasıl oluşturduğunu izlemek için tekrar çalıştırın. Yazdırarak izlemek zarif değildir, ama C'de hızlıdır ve her zaman işe yarar - bir hata ayıklayıcı size daha fazlasını söyler, bir printf ise bir şeyi hemen söyler.

İki alışkanlık bunun karmaşaya dönüşmesini engeller. Yorum satırına alınmış kodu işlemeden (commit) önce silin; sürüm denetimi eski sürümü hatırlar, sizin hatırlamanıza gerek yok. Ve devre dışı bir satırı bilerek bıraktığınızda, yanına bir notla nedenini söyleyin.

Belgeleme Yorumları

Bir fonksiyonun üstündeki blok yorum, ne yaptığını, parametrelerinin ne anlama geldiğini ve onunla ilgili şaşırtıcı her şeyi açıkladığınız yerdir.

#include <stdio.h>

/*
 * celsius_to_fahrenheit
 * ---------------------
 * Santigrat derece cinsinden bir sicakligi Fahrenheit'a cevirir.
 *
 *   c: girdi sicakligi, Santigrat cinsinden
 *
 * Fahrenheit cinsinden esdeger sicakligi dondurur.
 */
double celsius_to_fahrenheit(double c) {
    return c * 9.0 / 5.0 + 32.0;
}

int main(void) {
    printf("100C = %.1fF\n", celsius_to_fahrenheit(100.0));
    printf("0C   = %.1fF\n", celsius_to_fahrenheit(0.0));
    return 0;
}

Doxygen gibi araçlar bunun gibi yapılandırılmış yorumları okur ve başvuru belgeleri üretir. Doxygen'in kendi tarzı @param ve @return etiketleriyle /** ... */ kullanır:

/**
 * Santigradı Fahrenheit'a çevirir.
 * @param c Santigrat cinsinden sıcaklık
 * @return aynı sıcaklığın Fahrenheit karşılığı
 */
double celsius_to_fahrenheit(double c);

Kendi kodunuz için ikisi de uygundur. Önemli olan, yorumun insanların okuduğu bildirimin yanında - genellikle başlık dosyasında - durması, gerçekleştirimin içine gömülmemesidir.

Neyi Yorumlamaya Değer

Gerçek kod tabanlarıyla temastan sağ çıkan kural: neyi değil, nedenini yorumlayın.

i++;  // i'yi artır          <- kodun söylemediği hiçbir şey söylemiyor

/* BOM'u atla: eski sistemin dışa aktardığı dosyalar
   verinin parçası olmayan üç baytla başlar. */
offset += 3;

İkinci yorum, kodun hiçbir yerinde olmayan bilgi içerir. Birincisi, sonunda tarif ettiği satırla çelişecek gürültüdür, çünkü kod değiştiğinde yorumlar güncellenmez.

Özellikle C'de bir yoruma gerçekten değen şeyler:

• Bu belleğin sahibi kim. Bir fonksiyon, çağıranın free etmesi gereken bir gösterici döndürüyorsa bunu söyleyin. C'nin bunu türde ifade etmenin bir yolu yoktur.
• Birimler ve aralıklar. int timeout; belirsizdir - saniye mi milisaniye mi?
• Aşikâr olmayan doğruluk. Döngünün neden n - 1'de durduğu, bu dönüşümün neden güvenli olduğu, tamponun neden 256 bayt olduğu.
• Kasıtlı tuhaflık. Hata gibi görünüp olmayan kod, etiketlenmedikçe gelecekteki okuyuculardan "düzeltme" çeker.

#include <stdio.h>
#include <string.h>

int main(void) {
    char name[32];  /* 31 karakter arti sonlandirici '\0' */

    /* Kaynak tamponu doldurursa strncpy sonlandirici EKLEMEZ,
       o yuzden birini kendimiz yaziyoruz. */
    strncpy(name, "Ada Lovelace", sizeof(name) - 1);
    name[sizeof(name) - 1] = '\0';

    printf("Isim: %s\n", name);
    return 0;
}

O yorum yerini hak eder: altındaki satır gereksiz görünür ve değildir.

Metinlerin İçindeki Yorumlar Yorum Değildir

Son bir ayrıntı. Yorum işaretlerinin bir metin sabitinin ya da karakter sabitinin içinde özel bir anlamı yoktur:

#include <stdio.h>

int main(void) {
    printf("Ilerleme: 50%% // yorum degil\n");
    printf("Yol /* hala sadece metin */\n");
    return 0;
}

Her iki satır da eksiksiz yazdırılır. Derleyici metinleri yorumları aramadan önce belirteçlere ayırır, dolayısıyla tırnak içindeki // yalnızca iki karakterdir. (İlk satırdaki %%, printf ile gerçek bir yüzde işaretini böyle yazdırırsınız - tek başına % bir biçim belirteci başlatır.)