Komentar di C: Penjelasan // dan /* */

Komentar adalah teks yang dibuang oleh compiler. Komentar ada semata-mata untuk orang yang membaca kodenya nanti, dan salah satunya biasanya kamu sendiri. C menyediakan dua bentuk, dan memahami kapan masing-masing tepat dipakai hanya butuh sekitar dua menit.

Dua Bentuk Komentar

#include <stdio.h>

int main(void) {
    // A single-line comment: everything after // to the end of the line.

    /* A block comment.
       It can span as many lines as you like
       and ends only at the closing marker. */

    printf("Comments never reach the output.\n");  // they can trail code too
    return 0;
}

Jalankan: output-nya hanya satu baris. Kedua komentar sudah dihapus sebelum compiler mem-parse program, jadi tidak ada biaya saat program berjalan dan tidak menambah apa pun ke file executable.

// berlaku sampai akhir baris fisik. Tidak ada yang bisa mengikutinya di baris itu, jadi kode ini tidak bekerja seperti kelihatannya:

int x = 5;  // set x to five  int y = 6;   /* y is never declared */

/* ... */ berakhir di */ yang pertama, di mana pun letaknya. Komentar ini bisa dimulai dan diakhiri di tengah baris, yang sesekali berguna:

int total = price /* before tax */ + shipping;

Kenapa Ada Dua Gaya

/* */ adalah C asli, dari tahun 1972. // berasal dari C++ dan baru resmi ditambahkan ke C di C99. Sejarah itu menjelaskan sesuatu yang akan kamu perhatikan saat membaca kode lama: library yang ditulis agar portabel ke C89 memakai /* */ bahkan untuk komentar satu baris, karena // akan gagal dikompilasi di toolchain lama yang masih mereka dukung.

Saat ini setiap compiler yang kemungkinan kamu pakai menerima keduanya. Gunakan // untuk catatan biasa dan /* */ kalau komentarnya memang membentang beberapa baris. Kalau targetmu compiler embedded yang sangat lama, periksa dulu sebelum mengandalkan //.

Komentar Tidak Bisa Disarangkan

Inilah satu-satunya jebakan yang sebenarnya:

/* Disable this section for now
   int a = compute();
   /* the classic helper - keep an eye on it */
   int b = a * 2;
*/

Komentar blok berakhir di */ yang pertama, yaitu yang ada di baris 3. Baris 4 dan 5 kemudian menjadi kode aktif lagi, dan */ di akhir baris 6 menjadi error sintaks. Pesan compiler menunjuk ke baris terakhir dan sama sekali tidak membantu menjelaskan penyebabnya.

Solusinya adalah memakai preprocessor, yang memang bisa menangani nesting:

#if 0
    int a = compute();
    /* the classic helper - keep an eye on it */
    int b = a * 2;
#endif

#if 0 tidak pernah bernilai true, jadi preprocessor menghapus semuanya sampai #endif sebelum compiler melihatnya. Cara ini tetap aman meski di dalamnya ada komentar, tanda kutip, dan blok #if lain, dan mudah dicari saat kamu merapikan kode.

Menonaktifkan Kode Saat Debugging

Menghapus satu baris untuk sementara adalah pemakaian komentar yang paling umum sehari-hari. Saat program berperilaku aneh, menonaktifkan satu pernyataan demi satu memberi tahu kamu mana yang berpengaruh.

#include <stdio.h>

int main(void) {
    int total = 0;

    for (int i = 1; i <= 5; i++) {
        total += i;
        // printf("step %d: total = %d\n", i, total);  /* enable to trace */
    }

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

Hapus tanda komentar pada printf lalu jalankan lagi untuk melihat perulangan membangun jawabannya. Melacak dengan print memang tidak elegan, tetapi di C cara ini cepat dan selalu berhasil: debugger memberi tahu lebih banyak, sedangkan printf langsung memberi tahu sesuatu.

Dua kebiasaan menjaga agar ini tidak jadi berantakan. Hapus kode yang dinonaktifkan sebelum kamu commit; version control mengingat versi lamanya, jadi kamu tidak perlu. Lalu kalau kamu sengaja meninggalkan baris yang dinonaktifkan, tulis alasannya di catatan di sebelahnya.

Komentar Dokumentasi

Komentar blok di atas sebuah fungsi adalah tempat kamu menjelaskan apa yang dilakukannya, apa arti parameternya, dan apa pun yang mengejutkan tentangnya.

#include <stdio.h>

/*
 * celsius_to_fahrenheit
 * ---------------------
 * Converts a temperature in degrees Celsius to degrees Fahrenheit.
 *
 *   c: the input temperature, in Celsius
 *
 * Returns the equivalent temperature in Fahrenheit.
 */
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;
}

Tool seperti Doxygen membaca komentar terstruktur seperti ini dan menghasilkan dokumentasi referensi. Gaya Doxygen sendiri memakai /** ... */ dengan tag @param dan @return:

/**
 * Converts Celsius to Fahrenheit.
 * @param c temperature in Celsius
 * @return the same temperature in Fahrenheit
 */
double celsius_to_fahrenheit(double c);

Keduanya boleh untuk kodemu sendiri. Yang penting, komentar itu berada di sebelah deklarasi yang dibaca orang, biasanya di header file, bukan terkubur di implementasinya.

Apa yang Layak Diberi Komentar

Aturan yang tetap bertahan di codebase sungguhan: beri komentar tentang alasannya, bukan tentang apa yang dilakukan.

i++;  // increment i          <- says nothing the code did not

/* Skip the BOM: files exported by the old system start with
   three bytes that are not part of the data. */
offset += 3;

Komentar kedua berisi informasi yang tidak ada di mana pun dalam kode. Komentar pertama hanyalah gangguan yang suatu saat akan bertentangan dengan baris yang dijelaskannya, karena komentar tidak ikut diperbarui saat kodenya berubah.

Hal-hal yang benar-benar layak diberi komentar, khususnya di C:

• Siapa pemilik memori ini. Kalau sebuah fungsi mengembalikan pointer yang harus di-free oleh pemanggil, tuliskan. C tidak punya cara untuk menyatakannya lewat tipe.
• Satuan dan rentang. int timeout; ambigu: detik atau milidetik?
• Kebenaran yang tidak jelas. Kenapa perulangan berhenti di n - 1, kenapa cast ini aman, kenapa buffer-nya 256 byte.
• Keanehan yang disengaja. Kode yang terlihat seperti bug padahal bukan akan mengundang "perbaikan" dari pembaca berikutnya kalau tidak diberi label.

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

int main(void) {
    char name[32];  /* 31 characters plus the terminating '\0' */

    /* strncpy does NOT add a terminator if the source fills the buffer,
       so we write one ourselves. */
    strncpy(name, "Ada Lovelace", sizeof(name) - 1);
    name[sizeof(name) - 1] = '\0';

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

Komentar itu memang pantas ada: baris di bawahnya terlihat berlebihan, padahal tidak.

Komentar di Dalam String Bukan Komentar

Satu detail terakhir. Penanda komentar tidak punya arti khusus di dalam string literal atau konstanta karakter:

#include <stdio.h>

int main(void) {
    printf("Progress: 50%% // not a comment\n");
    printf("Path is /* still just text */\n");
    return 0;
}

Kedua baris dicetak lengkap. Compiler memecah string menjadi token sebelum mencari komentar, jadi // di dalam tanda kutip hanyalah dua karakter. (%% di baris pertama adalah cara mencetak tanda persen apa adanya dengan printf: % saja akan memulai format specifier.)