Apa yang salah dengan komentar yang menjelaskan kode kompleks?


236

Banyak orang mengklaim bahwa "komentar harus menjelaskan 'mengapa', tetapi tidak 'bagaimana'". Yang lain mengatakan bahwa "kode harus mendokumentasikan diri sendiri" dan komentar harus langka. Robert C. Martin mengklaim bahwa (diucapkan dengan kata-kata saya sendiri) sering "komentar adalah permintaan maaf untuk kode yang ditulis dengan buruk".

Pertanyaan saya adalah sebagai berikut:

Apa yang salah dengan menjelaskan algoritma yang rumit atau potongan kode yang panjang dan berbelit-belit dengan komentar deskriptif?

Dengan cara ini, alih-alih pengembang lain (termasuk Anda sendiri) harus membaca seluruh algoritme baris demi baris untuk mengetahui apa yang dilakukannya, mereka hanya dapat membaca komentar deskriptif ramah yang Anda tulis dalam bahasa Inggris.

Bahasa Inggris 'dirancang' agar mudah dipahami oleh manusia. Java, Ruby atau Perl, bagaimanapun, telah dirancang untuk menyeimbangkan keterbacaan manusia dan keterbacaan komputer, sehingga mengurangi keterbacaan teks oleh manusia. Seorang manusia dapat memahami sepotong bahasa Inggris lebih cepat sehingga dia dapat memahami sepotong kode dengan makna yang sama (selama operasi itu tidak sepele).

Jadi setelah menulis sepotong kode kompleks yang ditulis dalam bahasa pemrograman yang dapat dibaca sebagian manusia, mengapa tidak menambahkan komentar deskriptif dan ringkas yang menjelaskan pengoperasian kode dalam bahasa Inggris yang ramah dan dapat dimengerti?

Beberapa orang akan mengatakan "kode seharusnya tidak sulit untuk dimengerti", "membuat fungsi kecil", "gunakan nama deskriptif", "jangan menulis kode spaghetti".

Tapi kita semua tahu itu tidak cukup. Ini hanyalah pedoman - yang penting dan berguna - tetapi mereka tidak mengubah fakta bahwa beberapa algoritma rumit. Dan karena itu sulit untuk dipahami ketika membacanya baris demi baris.

Apakah benar-benar buruk untuk menjelaskan algoritma yang rumit dengan beberapa baris komentar tentang operasi umum itu? Apa yang salah dengan menjelaskan kode rumit dengan komentar?


14
Jika berbelit-belit, coba refactoring menjadi potongan-potongan kecil.
Vaughan Hilts

151
Secara teori, tidak ada perbedaan antara teori dan praktik. Dalam praktiknya, ada.
Scott Leadley

5
@ mattnz: lebih langsung, pada saat Anda menulis komentar Anda tenggelam dalam masalah yang dipecahkan kode ini. Lain kali Anda mengunjungi, Anda akan memiliki sedikit kemampuan dengan masalah ini .
Steve Jessop

26
"Apa" yang dilakukan fungsi atau metode harus jelas dari namanya. Cara kerjanya jelas dari kodenya. Mengapa dilakukan dengan cara ini, asumsi tersirat apa yang digunakan, makalah mana yang perlu dibaca untuk memahami algoritme, dll. - harus dalam komentar.
SK-logic

11
Saya merasa banyak tanggapan di bawah ini sengaja salah menafsirkan pertanyaan Anda. Tidak ada yang salah dengan mengomentari kode Anda. Jika Anda merasa perlu menulis komentar yang jelas, maka Anda perlu melakukannya.
Tony Ennis

Jawaban:


408

Dalam istilah awam:

  • Tidak ada yang salah dengan komentar per se. Yang salah adalah menulis kode yang memerlukan komentar semacam itu, atau dengan anggapan tidak apa-apa untuk menulis kode yang berbelit-belit selama Anda menjelaskannya ramah dalam bahasa Inggris.
  • Komentar tidak diperbarui secara otomatis ketika Anda mengubah kode. Itu sebabnya sering kali komentar tidak sinkron dengan kode.
  • Komentar tidak membuat kode lebih mudah untuk diuji.
  • Meminta maaf tidak buruk. Apa yang Anda lakukan yang meminta maaf untuk (menulis kode yang tidak mudah dimengerti) adalah buruk.
  • Seorang programmer yang mampu menulis kode sederhana untuk memecahkan masalah yang kompleks lebih baik daripada yang menulis kode kompleks dan kemudian menulis komentar panjang menjelaskan apa yang dikerjakan oleh kode-nya.

Intinya:

Menjelaskan dirimu baik, tidak perlu melakukannya lebih baik.


91
Sering kali tidak mungkin untuk membenarkan kode penulisan ulang uang yang dikeluarkan majikan untuk lebih jelas, ketika komentar yang baik dapat melakukan pekerjaan dalam waktu yang jauh lebih singkat. Seorang programmer yang patuh harus menggunakan penilaiannya setiap kali.
aecolley

34
@ aecolley Menulis kode penjelasan sendiri untuk memulai adalah lebih baik.
Tulains Córdova

127
Terkadang kode penjelasan sendiri tidak cukup efisien untuk menyelesaikan masalah dengan HW&SW hari ini. Dan logika bisnis terkenal ... berkelok-kelok. Subset masalah yang memiliki solusi perangkat lunak yang elegan jauh lebih kecil daripada serangkaian masalah yang secara ekonomi berguna untuk dipecahkan.
Scott Leadley

62
@rwong: sebaliknya saya sering menemukan diri saya menulis lebih banyak komentar dalam logika bisnis, karena penting untuk menunjukkan dengan tepat bagaimana kode berbaris dengan persyaratan yang dinyatakan: "ini adalah garis yang mencegah kita semua masuk penjara karena penipuan kawat di bawah Bagian Apa Pun KUHP ". Jika itu hanya sebuah algoritma, yah, seorang programmer dapat mengetahui tujuan dari awal jika benar-benar diperlukan. Untuk logika bisnis, Anda memerlukan pengacara dan klien di ruangan yang sama secara bersamaan. Mungkin "akal sehat" saya berada dalam domain yang berbeda dari rata-rata programmer aplikasi ;-)
Steve Jessop

29
@ user61852 Kecuali apa yang cukup jelas bagi Anda yang baru saja menulis kode itu dan menghabiskan $ periode terakhir yang terbenam di dalamnya mungkin tidak jelas bagi Anda yang harus mempertahankan atau mengeditnya lima tahun dari sekarang, apalagi semua kemungkinan orang yang bukan Anda yang mungkin harus melihatnya. "Cukup jelas" adalah grail suci definisi yang samar-samar.
Shadur

110

Ada banyak alasan berbeda untuk kode menjadi rumit atau membingungkan. Alasan paling umum paling baik diatasi dengan refactoring kode untuk membuatnya kurang membingungkan, bukan dengan menambahkan komentar dalam bentuk apa pun.

Namun, ada beberapa kasus di mana komentar yang dipilih dengan baik adalah pilihan terbaik.

  • Jika algoritma itu sendiri yang rumit dan membingungkan, bukan hanya implementasinya — jenis yang ditulis dalam jurnal matematika dan selalu disebut sebagai Algoritma Mbogo — maka Anda memberikan komentar di awal implementasi, membaca sesuatu seperti "Ini adalah Algoritma Mbogo untuk widget refrobnicating, awalnya dijelaskan di sini: [URL kertas]. Implementasi ini berisi perbaikan oleh Alice dan Carol [URL makalah lain]." Jangan mencoba lebih detail dari itu; jika seseorang membutuhkan lebih banyak detail, mereka mungkin perlu membaca seluruh makalah.

  • Jika Anda telah mengambil sesuatu yang dapat ditulis sebagai satu atau dua baris dalam beberapa notasi khusus dan memperluasnya menjadi gumpalan besar kode imperatif, menempatkan satu atau dua baris notasi khusus tersebut dalam komentar di atas fungsi adalah cara yang baik untuk beri tahu pembaca apa yang harus dilakukan. Ini pengecualian untuk argumen "tetapi bagaimana jika komentar tidak sinkron dengan kode", karena notasi khusus mungkin lebih mudah untuk menemukan bug daripada kode. (Ini sebaliknya jika Anda menulis spesifikasi dalam bahasa Inggris.) Contoh yang baik di sini: https://dxr.mozilla.org/mozilla-central/source/layout/style/nsCSSScanner.cpp#1057 ...

    /**
     * Scan a unicode-range token.  These match the regular expression
     *
     *     u\+[0-9a-f?]{1,6}(-[0-9a-f]{1,6})?
     *
     * However, some such tokens are "invalid".  There are three valid forms:
     *
     *     u+[0-9a-f]{x}              1 <= x <= 6
     *     u+[0-9a-f]{x}\?{y}         1 <= x+y <= 6
     *     u+[0-9a-f]{x}-[0-9a-f]{y}  1 <= x <= 6, 1 <= y <= 6
    
  • Jika kode secara keseluruhan mudah, tetapi berisi satu atau dua hal yang terlihat terlalu berbelit-belit, tidak perlu, atau hanya salah, tetapi harus seperti itu karena alasan, maka Anda memberikan komentar tepat di atas bit yang tampak mencurigakan, di mana Anda nyatakan alasannya . Inilah contoh sederhana, di mana satu-satunya hal yang perlu dijelaskan adalah mengapa sebuah konstanta memiliki nilai tertentu.

    /* s1*s2 <= SIZE_MAX if s1 < K and s2 < K, where K = sqrt(SIZE_MAX+1) */
    const size_t MUL_NO_OVERFLOW = ((size_t)1) << (sizeof(size_t) * 4);
    if ((nmemb >= MUL_NO_OVERFLOW || size >= MUL_NO_OVERFLOW) &&
        nmemb > 0 && SIZE_MAX / nmemb < size)
      abort();
    

25
Itu keterlaluan, 4seharusnya CHAR_BIT / 2;-)
Steve Jessop

@SteveJessop: Apakah ada yang menghalangi implementasi di mana CHAR_BITS16 dan sizeof (size_t) adalah 2, tetapi nilai maksimum size_t adalah misalnya 2 ^ 20 [size_t mengandung 12 bit padding]?
supercat

2
@supercat Saya tidak melihat apa pun yang jelas menghalangi hal itu di C99, yang berarti bahwa contoh itu secara teknis salah. Ini kebetulan diambil dari (versi yang sedikit dimodifikasi) dari OpenBSD reallocarray, dan OpenBSD umumnya tidak percaya pada kemungkinan yang tidak terjadi pada ABI mereka .
zwol

3
@Zack: Jika kode ini dirancang berdasarkan asumsi POSIX, menggunakan CHAR_BITS mungkin memberi kesan bahwa kode tersebut dapat bekerja dengan nilai selain 8.
supercat

2
@ Zack: Agar tipe unsigned lebar-lebar berguna, semantiknya harus ditentukan tanpa ukuran int. Karena, diberikan uint32_t x,y,z;, arti (x-y) > ztergantung pada ukuran int. Lebih lanjut, bahasa yang dirancang untuk menulis kode yang kuat harus memungkinkan pemrogram untuk membedakan antara jenis di mana perhitungan diharapkan melebihi kisaran jenis dan harus membungkus secara diam-diam, versus satu di mana perhitungan melebihi kisaran jenis yang harus dijebak, versus yang mana perhitungan tidak diharapkan untuk melebihi kisaran tipe, tapi ...
supercat

61

Jadi apa yang salah dengan menjelaskan kode rumit dengan komentar?

Ini bukan masalah benar atau salah, tetapi tentang 'praktik terbaik', sebagaimana didefinisikan dalam artikel Wikipedia :

Praktik terbaik adalah metode atau teknik yang secara konsisten menunjukkan hasil lebih unggul daripada yang dicapai dengan cara lain, dan yang digunakan sebagai tolok ukur.

Jadi praktik terbaik adalah mencoba memperbaiki kode terlebih dahulu, dan menggunakan bahasa Inggris jika itu tidak mungkin.

Ini bukan undang-undang, tetapi jauh lebih umum untuk menemukan kode komentar yang memerlukan refactoring daripada kode refactored yang membutuhkan komentar, praktik terbaik mencerminkan hal ini.


42
+1 untuk "jauh lebih umum untuk menemukan kode komentar yang memerlukan refactoring daripada kode refactored yang membutuhkan komentar"
Brandon

7
Oke, tapi seberapa sering komentar itu: //This code seriously needs a refactor
Erik Reppen

2
Tentu saja, apa yang disebut praktik terbaik yang tidak didukung oleh studi ilmiah yang ketat hanyalah pendapat.
Blrfl

54

Suatu hari akan tiba ketika kode Anda yang indah, dibuat dengan sempurna, terstruktur dengan baik dan mudah dibaca tidak akan berfungsi. Atau itu tidak akan bekerja dengan cukup baik. Atau kasus khusus akan muncul di tempat yang tidak berfungsi dan perlu disesuaikan.

Pada titik itu, Anda perlu melakukan sesuatu yang mengubah beberapa hal agar berfungsi dengan benar. Terutama dalam kasus di mana ada masalah kinerja, tetapi juga sering dalam skenario di mana salah satu pustaka, API, layanan web, permata atau sistem operasi yang Anda kerjakan tidak berperilaku seperti yang diharapkan, Anda dapat membuat saran yang tidak tentu tidak elegan, tetapi kontra-intuitif atau tidak jelas.

Jika Anda tidak memiliki komentar untuk menjelaskan mengapa Anda memilih pendekatan itu, ada peluang yang sangat bagus bahwa seseorang di masa depan (dan seseorang yang mungkin adalah Anda) akan melihat kode tersebut, lihat bagaimana hal itu dapat "diperbaiki" untuk sesuatu yang lebih mudah dibaca dan elegan dan secara tidak sengaja membatalkan perbaikan Anda, karena itu tidak terlihat seperti perbaikan.

Jika semua orang selalu menulis kode yang sempurna maka akan jelas bahwa kode yang terlihat tidak sempurna itu bekerja di sekitar beberapa intervensi rumit dari dunia nyata, tetapi bukan itu cara kerjanya. Sebagian besar programmer sering menulis kode yang membingungkan atau agak kusut sehingga ketika kita menjumpai ini adalah kecenderungan alami untuk merapikannya. Saya bersumpah masa lalu saya adalah orang idiot yang sebenarnya setiap kali saya membaca kode lama yang saya tulis.

Jadi saya tidak menganggap komentar sebagai permintaan maaf untuk kode buruk, tapi mungkin sebagai penjelasan mengapa Anda tidak melakukan hal yang jelas. Memiliki // The standard approach doesn't work against the 64 bit version of the Frobosticate Libraryakan memungkinkan pengembang di masa depan, termasuk diri Anda di masa depan, untuk memperhatikan bagian dari kode dan menguji terhadap perpustakaan itu. Tentu, Anda mungkin memasukkan komentar di komit kontrol sumber Anda juga, tetapi orang-orang hanya akan melihatnya setelah ada yang tidak beres. Mereka akan membaca komentar kode saat mereka mengubah kode.

Orang-orang yang memberi tahu kami bahwa kami harus selalu menulis kode yang sempurna secara teoritis tidak selalu orang dengan banyak pengalaman pemrograman di lingkungan dunia nyata. Kadang-kadang Anda perlu menulis kode yang berkinerja ke tingkat tertentu, kadang-kadang Anda perlu beroperasi dengan sistem yang tidak sempurna. Itu tidak berarti bahwa Anda tidak dapat melakukan ini dengan cara yang elegan dan ditulis dengan baik, tetapi solusi yang tidak jelas perlu penjelasan.

Ketika saya menulis kode untuk proyek-proyek hobi yang saya tahu tidak akan pernah dibaca orang lain, saya masih berkomentar bagian yang saya anggap membingungkan - misalnya, setiap geometri 3D melibatkan matematika yang saya tidak sepenuhnya di rumah dengan - karena saya tahu kapan saya kembali dalam enam bulan saya akan benar-benar lupa bagaimana melakukan hal ini. Itu bukan permintaan maaf untuk kode buruk, itu pengakuan keterbatasan pribadi. Yang akan saya lakukan dengan membiarkannya tanpa komentar adalah menciptakan lebih banyak pekerjaan untuk diri saya di masa depan. Saya tidak ingin masa depan saya harus mempelajari kembali sesuatu yang tidak perlu jika saya bisa menghindarinya sekarang. Nilai apa yang mungkin dimiliki nilai itu?


5
@Christian ya? Baris pertama merujuk pernyataan itu, tentu saja, tetapi di luar itu sedikit lebih luas seperti yang saya mengerti.
glenatron

9
"Aku bersumpah masa laluku adalah idiot yang sebenarnya setiap kali aku membaca kode lama yang aku tulis." Empat tahun dalam karir pengembangan saya dan saya menemukan ini adalah kejadian yang terjadi setiap kali saya melihat sesuatu yang lebih dari 6 bulan atau lebih.
Ken

6
Dalam banyak kasus, informasi historis yang paling informatif dan berguna berkaitan dengan hal-hal yang dianggap tetapi diputuskan. Ada banyak kasus di mana seseorang memilih pendekatan X untuk sesuatu dan beberapa pendekatan lain Y akan tampak lebih baik; dalam beberapa kasus tersebut, Y akan "hampir" bekerja lebih baik daripada X, tetapi ternyata memiliki beberapa masalah yang tidak dapat diatasi. Jika Y dihindari karena masalah-masalah itu, pengetahuan seperti itu dapat membantu mencegah orang lain membuang-buang waktu mereka pada upaya yang gagal untuk menerapkan pendekatan Y.
supercat

4
Sehari-hari saya banyak menggunakan pekerjaan dalam komentar kemajuan - mereka tidak ada di sana untuk jangka panjang, tetapi memasukkan catatan TODO atau bagian singkat untuk mengingatkan saya apa yang akan saya lakukan selanjutnya dapat bermanfaat pengingat di pagi hari.
glenatron

1
@Lilienthal, saya tidak berpikir bahwa para terakhir dibatasi untuk proyek pribadi — dia berkata "... Saya masih berkomentar bagian yang saya anggap membingungkan."
Wildcard

29

Kebutuhan akan komentar berbanding terbalik dengan tingkat abstraksi kode.

Misalnya, Bahasa Assembly, untuk tujuan praktis, tidak dapat dipahami tanpa komentar. Berikut adalah kutipan dari program kecil yang menghitung dan mencetak ketentuan dari seri Fibonacci :

main:   
; initializes the two numbers and the counter.  Note that this assumes
; that the counter and num1 and num2 areas are contiguous!
;
    mov ax,'00'                     ; initialize to all ASCII zeroes
    mov di,counter                  ; including the counter
    mov cx,digits+cntDigits/2       ; two bytes at a time
    cld                             ; initialize from low to high memory
    rep stosw                       ; write the data
    inc ax                          ; make sure ASCII zero is in al
    mov [num1 + digits - 1],al      ; last digit is one
    mov [num2 + digits - 1],al      ; 
    mov [counter + cntDigits - 1],al

    jmp .bottom         ; done with initialization, so begin

.top
    ; add num1 to num2
    mov di,num1+digits-1
    mov si,num2+digits-1
    mov cx,digits       ; 
    call    AddNumbers  ; num2 += num1
    mov bp,num2         ;
    call    PrintLine   ;
    dec dword [term]    ; decrement loop counter
    jz  .done           ;

    ; add num2 to num1
    mov di,num2+digits-1
    mov si,num1+digits-1
    mov cx,digits       ;
    call    AddNumbers  ; num1 += num2
.bottom
    mov bp,num1         ;
    call    PrintLine   ;
    dec dword [term]    ; decrement loop counter
    jnz .top            ;
.done
    call    CRLF        ; finish off with CRLF
    mov ax,4c00h        ; terminate
    int 21h             ;

Bahkan dengan komentar, itu bisa sangat rumit untuk grok.

Contoh Modern: Regex seringkali merupakan konstruksi abstraksi yang sangat rendah (huruf kecil, angka 0, 1, 2, baris baru, dll). Mereka mungkin perlu komentar dalam bentuk sampel (Bob Martin, IIRC, tidak mengakui ini). Berikut adalah regex yang (menurut saya) harus cocok dengan HTTP (S) dan URL FTP:

^(((ht|f)tp(s?))\://)?(www.|[a-zA-Z].)[a-zA-Z0-9\-\.]+\.(com|edu|gov|m
+il|net|org|biz|info|name|museum|us|ca|uk)(\:[0-9]+)*(/($|[a-zA-Z0-9\.
+\,\;\?\'\\\+&amp;%\$#\=~_\-]+))*$

Saat bahasa berkembang hierarki abstraksi, programmer dapat menggunakan abstraksi menggugah (nama variabel, nama fungsi, nama kelas, nama modul, antarmuka, panggilan balik, dll) untuk menyediakan dokumentasi bawaan. Untuk mengabaikan mengambil keuntungan dari ini, dan menggunakan komentar untuk menulis di atasnya itu malas, merugikan dan tidak sopan dari pengelola.

Saya sedang berpikir untuk Numerical Recipes di C diterjemahkan sebagian besar verbatim untuk Numerical Recipes dalam C ++ , yang saya simpulkan dimulai sebagai Numerical Recipes (di FORTRAN), dengan semua variabel a, aa, b, c, cc, dll dipertahankan melalui setiap versi. Algoritme mungkin benar, tetapi mereka tidak memanfaatkan abstraksi bahasa yang disediakan. Dan mereka membuatku kesal. Contoh dari artikel Dr. Dobbs - Fast Fourier Transform :

void four1(double* data, unsigned long nn)
{
    unsigned long n, mmax, m, j, istep, i;
    double wtemp, wr, wpr, wpi, wi, theta;
    double tempr, tempi;

    // reverse-binary reindexing
    n = nn<<1;
    j=1;
    for (i=1; i<n; i+=2) {
        if (j>i) {
            swap(data[j-1], data[i-1]);
            swap(data[j], data[i]);
        }
        m = nn;
        while (m>=2 && j>m) {
            j -= m;
            m >>= 1;
        }
        j += m;
    };

    // here begins the Danielson-Lanczos section
    mmax=2;
    while (n>mmax) {
        istep = mmax<<1;
        theta = -(2*M_PI/mmax);
        wtemp = sin(0.5*theta);
        wpr = -2.0*wtemp*wtemp;
        wpi = sin(theta);
        wr = 1.0;
        wi = 0.0;
        for (m=1; m < mmax; m += 2) {
            for (i=m; i <= n; i += istep) {
                j=i+mmax;
                tempr = wr*data[j-1] - wi*data[j];
                tempi = wr * data[j] + wi*data[j-1];

                data[j-1] = data[i-1] - tempr;
                data[j] = data[i] - tempi;
                data[i-1] += tempr;
                data[i] += tempi;
            }
            wtemp=wr;
            wr += wr*wpr - wi*wpi;
            wi += wi*wpr + wtemp*wpi;
        }
        mmax=istep;
    }
}

Sebagai kasus khusus tentang abstraksi, setiap bahasa memiliki idiom / cuplikan kode kanonik untuk tugas-tugas umum tertentu (menghapus daftar yang terkait dinamis dalam C), dan terlepas dari bagaimana tampilannya, mereka tidak boleh didokumentasikan. Pemrogram harus mempelajari idiom-idiom ini, karena mereka adalah bagian tidak resmi dari bahasa tersebut.

Jadi kesimpulannya: Kode non-idiomatik yang dibangun dari blok bangunan tingkat rendah yang tidak dapat dihindari membutuhkan komentar. Dan ini perlu WAAAAY kurang dari itu terjadi.


1
Tidak ada yang benar-benar harus menulis baris seperti ini dalam bahasa assembly: dec dword [term] ; decrement loop counter. Di sisi lain, apa yang tidak ada pada contoh bahasa majelis Anda adalah komentar sebelum setiap "paragraf kode" menjelaskan apa yang dilakukan oleh blok kode berikutnya. Dalam hal itu, komentar biasanya akan setara dengan satu baris dalam pseudocode, seperti ;clear the screen, diikuti oleh 7 baris yang diperlukan untuk menghapus layar.
Scott Whitlock

1
Ya, ada apa yang saya anggap beberapa komentar yang tidak perlu dalam sampel perakitan, tetapi untuk bersikap adil, itu cukup mewakili gaya Majelis 'Baik'. Bahkan dengan prolog paragraf satu atau dua baris, kodenya akan sangat sulit untuk diikuti. Saya memahami sampel ASM lebih baik daripada contoh FFT. Saya memprogram FFT di C ++ di sekolah pascasarjana, dan itu tidak terlihat seperti ini, tapi kemudian kami menggunakan STL, iterator, functors beberapa pemanggilan metode. Tidak secepat fungsi monolitik, tetapi jauh lebih mudah dibaca. Saya akan mencoba menambahkannya ke sampel NRinC ++.
Kristian H

Apakah maksud Anda ^(((ht|f)tps?)\:\/\/)?(www\.)*[a-zA-Z0-9\-\.]+\.(com|edu|gov|mil|net|org|biz|info|name|museum|us|ca|uk)(\:[0-9]+)*(\/($|[a-zA-Z0-9\.\,\;\?\'\\\+&%\$#\=~_\-]+))*$? Waspadai alamat numerik.
izabera

Poin saya kurang lebih: beberapa hal yang dibangun dari abstraksi level sangat rendah tidak mudah dibaca atau diverifikasi. Komentar (dan, jangan sampai terlalu jauh dari jalur, TEST) dapat bermanfaat, dan tidak merugikan. Pada saat yang sama, tidak menggunakan abstraksi level yang lebih tinggi yang tersedia (: alpha:: num: jika tersedia) membuat lebih sulit untuk dipahami, bahkan dengan komentar yang baik, daripada menggunakan abstraksi level yang lebih tinggi.
Kristian H

3
+1: "The need for comments is inversely proportional to the abstraction level of the code." Cukup banyak jumlah semuanya di sana.
Gerrat

21

Saya tidak percaya ada yang salah dengan komentar dalam kode. Gagasan bahwa komentar entah bagaimana buruk menurut pendapat saya adalah karena beberapa programmer mengambil terlalu banyak hal. Ada banyak bandwagoning di industri ini, terutama terhadap pandangan ekstrem. Di suatu tempat sepanjang jalan berkomentar kode menjadi setara dengan kode buruk dan saya tidak yakin mengapa.

Komentar memang memiliki masalah - Anda harus terus memperbaruinya saat Anda memperbarui kode yang mereka rujuk, yang jarang terjadi. Wiki atau sesuatu adalah sumber yang lebih tepat untuk dokumentasi menyeluruh tentang kode Anda. Kode Anda harus dapat dibaca tanpa memerlukan komentar. Kontrol versi atau catatan revisi harus menjadi tempat Anda menggambarkan perubahan kode yang Anda buat.

Namun, tidak ada satu pun di atas yang membatalkan penggunaan komentar. Kami tidak hidup di dunia yang ideal sehingga ketika salah satu di atas gagal karena alasan apa pun, saya lebih suka memiliki beberapa komentar untuk mundur.


18

Saya pikir Anda terlalu banyak membaca apa yang dia katakan. Ada dua bagian berbeda untuk keluhan Anda:

Apa yang salah dengan menjelaskan (1) algoritma yang kompleks atau (2) sepotong kode yang panjang dan berbelit-belit dengan komentar deskriptif?

(1) tidak bisa dihindari. Saya tidak berpikir bahwa Martin akan tidak setuju dengan Anda. Jika Anda menulis sesuatu seperti root kuadrat terbalik cepat , Anda akan memerlukan beberapa komentar, bahkan jika itu hanya "peretasan tingkat bit floating point jahat." Kecuali sesuatu yang sederhana seperti DFS atau pencarian biner, tidak mungkin orang yang membaca kode Anda akan memiliki pengalaman dengan algoritma itu, dan jadi saya pikir setidaknya harus disebutkan dalam komentar tentang apa itu.

Namun sebagian besar kode tidak (1). Jarang Anda akan menulis perangkat lunak yang tidak lain adalah implementasi mutex linting tangan, operasi aljabar linier yang tidak jelas dengan dukungan perpustakaan yang buruk, dan algoritme baru yang hanya diketahui oleh grup riset perusahaan Anda. Sebagian besar kode terdiri dari panggilan pustaka / framework / API, IO, boilerplate, dan unit test.

Ini adalah jenis kode yang dibicarakan Martin. Dan dia menjawab pertanyaan Anda dengan kutipan dari Kernighan dan Plaugher di bagian atas bab ini:

Jangan berkomentar kode buruk — tulis ulang.

Jika Anda memiliki bagian yang panjang dan berbelit-belit dalam kode Anda, Anda gagal menjaga kode Anda tetap bersih . Solusi terbaik untuk masalah ini adalah tidak menulis komentar sepanjang paragraf di bagian atas file untuk membantu pengembang masa depan mengatasi masalah itu; solusi terbaik adalah menulis ulang.

Dan inilah yang dikatakan Martin:

Penggunaan komentar yang tepat adalah untuk mengkompensasi kegagalan kami untuk mengekspresikan diri dalam kode ... Komentar selalu gagal. Kita harus memilikinya karena kita tidak bisa selalu mencari cara untuk mengekspresikan diri tanpa mereka, tetapi penggunaannya bukan merupakan alasan untuk perayaan.

Ini adalah milikmu (2). Martin setuju bahwa panjang, kode berbelit-belit memang membutuhkan komentar - tetapi ia menyalahkan kode itu di pundak programmer yang menulisnya, bukan gagasan samar-samar bahwa "kita semua tahu itu tidak cukup." Dia berpendapat bahwa:

Kode yang jelas dan ekspresif dengan sedikit komentar jauh lebih unggul daripada kode yang berantakan dan kompleks dengan banyak komentar. Daripada menghabiskan waktu Anda menulis komentar yang menjelaskan kekacauan yang Anda buat, habiskan untuk membersihkan kekacauan itu.


3
Jika seorang pengembang saya bekerja dengan hanya menulis "peretasan tingkat bit floating point jahat" untuk menjelaskan algoritma cepat kuadrat - mereka akan mendapatkan berbicara dengan saya. Selama mereka memasukkan referensi ke suatu tempat yang lebih berguna, aku akan senang.
Michael Anderson

8
Saya tidak setuju dalam satu cara - komentar yang menjelaskan bagaimana sesuatu yang buruk bekerja jauh lebih cepat. Mengingat beberapa kode yang kemungkinan tidak akan disentuh lagi (sebagian besar kode saya kira) maka komentar adalah solusi bisnis yang lebih baik daripada refactoring besar, yang sering memperkenalkan bug (karena perbaikan yang membunuh bug yang diandalkan masih merupakan bug). Dunia yang sempurna dengan kode yang mudah dimengerti tidak tersedia bagi kami.
gbjbaanb

2
@trysis haha, ya, tetapi di dunia di mana para programmer bertanggung jawab dan bukan pebisnis, mereka tidak akan pernah mengirim karena mereka selamanya menambal basis kode yang terus-menerus di-refactored dalam pencarian sia-sia untuk kesempurnaan.
gbjbaanb

4
@ Patrickrick hampir semua yang saya baca di web adalah tentang melakukannya dengan benar pertama kali. Hampir tidak ada yang mau menulis artikel tentang memperbaiki kekacauan! Fisikawan mengatakan "diberikan bola yang sempurna ..." Comp. Ilmuwan mengatakan "diberikan pengembangan greenfield ..."
gbjbaanb

2
Solusi terbaik adalah menulis ulang dengan waktu yang tidak terbatas; tetapi mengingat basis kode orang lain, tenggat waktu khas perusahaan, dan kenyataan; terkadang hal terbaik untuk dilakukan adalah mengomentari, menambahkan TODO: Refactor dan memasukkan refactor itu ke rilis berikutnya; dan perbaikan yang perlu dilakukan kemarin dilakukan sekarang. Yang penting dari semua pembicaraan idealis tentang hanya refactoring ini adalah tidak menjelaskan bagaimana segala sesuatunya bekerja di tempat kerja; kadang-kadang ada prioritas yang lebih tinggi dan tenggat waktu yang cukup segera yang akan mendahului memperbaiki kode kualitas buruk sebelumnya. Begitulah adanya.
hsanders

8

Apa yang salah dengan menjelaskan algoritma yang rumit atau potongan kode yang panjang dan berbelit-belit dengan komentar deskriptif?

Tidak ada yang seperti itu. Mendokumentasikan pekerjaan Anda adalah praktik yang baik.

Yang mengatakan, Anda memiliki dikotomi palsu di sini: menulis kode bersih vs menulis kode terdokumentasi - keduanya tidak bertentangan.

Yang harus Anda fokuskan adalah menyederhanakan dan mengabstraksi kode kompleks menjadi kode yang lebih sederhana, alih-alih berpikir "kode kompleks baik-baik saja asalkan dikomentari".

Idealnya, kode Anda harus sederhana dan didokumentasikan.

Dengan cara ini, alih-alih pengembang lain (termasuk Anda sendiri) harus membaca seluruh algoritme baris demi baris untuk mengetahui apa yang dilakukannya, mereka hanya dapat membaca komentar deskriptif ramah yang Anda tulis dalam bahasa Inggris.

Benar. Inilah sebabnya mengapa semua algoritma API publik Anda harus dijelaskan dalam dokumentasi.

Jadi setelah menulis sepotong kode kompleks yang ditulis dalam bahasa pemrograman yang dapat dibaca sebagian manusia, mengapa tidak menambahkan komentar deskriptif dan ringkas yang menjelaskan pengoperasian kode dalam bahasa Inggris yang ramah dan dapat dimengerti?

Idealnya, setelah menulis sepotong kode kompleks Anda harus (bukan daftar lengkap):

  • menganggapnya sebagai konsep (yaitu rencana untuk menulis ulang)
  • meresmikan titik masuk algoritme / antarmuka / peran / dll (menganalisis dan mengoptimalkan antarmuka, memformalkan abstraksi, prasyarat dokumen, kondisi akhir dan efek samping serta kasus kesalahan dokumen).
  • menulis tes
  • pembersihan dan refactor

Tidak satu pun dari langkah-langkah ini yang sepele untuk dilakukan (yaitu masing-masing dapat memakan waktu beberapa jam) dan imbalan untuk melakukannya tidak langsung. Dengan demikian, langkah-langkah ini (hampir) selalu dikompromikan (oleh pengembang memotong sudut, manajer memotong sudut, tenggat waktu, kendala pasar / kondisi dunia nyata lainnya, kurangnya pengalaman dll).

[...] beberapa algoritma rumit. Dan karena itu sulit untuk dipahami ketika membacanya baris demi baris.

Anda tidak perlu mengandalkan membaca implementasi untuk mengetahui apa yang dilakukan oleh API. Ketika Anda melakukan itu, Anda menerapkan kode klien berdasarkan pada implementasi (bukan antarmuka) dan itu berarti kopling modul Anda sudah melesat ke neraka, Anda berpotensi memperkenalkan dependensi tidak berdokumen dengan setiap baris kode baru yang Anda tulis, dan sudah menambahkan utang teknis.

Apakah benar-benar buruk untuk menjelaskan algoritma yang rumit dengan beberapa baris komentar tentang operasi umum itu?

Tidak - itu bagus. Menambahkan beberapa baris komentar saja tidak cukup.

Apa yang salah dengan menjelaskan kode rumit dengan komentar?

Fakta bahwa Anda seharusnya tidak memiliki kode yang rumit, jika itu bisa dihindari.

Untuk menghindari kode yang rumit, formalkan antarmuka Anda, belanjakan ~ 8 kali lebih banyak pada desain API daripada yang Anda habiskan untuk implementasi (Stepanov menyarankan untuk menghabiskan setidaknya 10x pada antarmuka, dibandingkan dengan implementasi), dan masuk ke dalam mengembangkan proyek dengan pengetahuan yang Anda membuat proyek, bukan hanya menulis beberapa algoritma.

Sebuah proyek melibatkan dokumentasi API, dokumentasi fungsional, pengukuran kode / kualitas, manajemen proyek dan sebagainya. Tidak satu pun dari proses ini yang merupakan langkah cepat yang harus dilakukan (mereka semua membutuhkan waktu, memerlukan pemikiran dan perencanaan, dan semuanya mengharuskan Anda untuk kembali secara berkala dan merevisi / melengkapinya dengan detail).


3
"Anda seharusnya tidak perlu mengandalkan membaca implementasi untuk mencari tahu apa yang dilakukan API." Terkadang hal ini terjadi pada Anda oleh upstream yang Anda berkomitmen untuk gunakan. Saya punya proyek yang sangat tidak memuaskan berserakan dengan komentar dari bentuk "kode Heath Robinson jelek berikut ada karena simpleAPI () tidak bekerja dengan baik pada perangkat keras ini meskipun apa yang diklaim oleh vendor".
pjc50

6

alih-alih pengembang lain (termasuk diri Anda sendiri) harus membaca seluruh algoritme baris demi baris untuk mengetahui apa yang dilakukannya, mereka hanya dapat membaca komentar deskriptif ramah yang Anda tulis dalam bahasa Inggris sederhana.

Saya akan menganggap ini sedikit penyalahgunaan "komentar". Jika programmer ingin membaca sesuatu daripada keseluruhan algoritma, maka untuk itulah fungsi dokumentasi itu. OK, jadi dokumentasi fungsi mungkin benar-benar muncul di komentar di sumber (mungkin untuk diekstraksi dengan alat doc), tetapi meskipun secara sintaksis itu adalah komentar sejauh yang dikompilasi oleh kompiler Anda, Anda harus menganggap mereka memisahkan hal-hal dengan tujuan yang berbeda. Saya tidak berpikir "komentar harus langka" berarti dimaksudkan untuk "dokumentasi harus langka" atau bahkan "pemberitahuan hak cipta harus langka"!

Komentar dalam fungsi ini untuk seseorang untuk membaca serta kode. Jadi, jika Anda memiliki beberapa baris dalam kode Anda yang sulit dimengerti, dan Anda tidak dapat membuatnya mudah dimengerti, maka komentar berguna bagi pembaca untuk digunakan sebagai pengganti untuk baris-baris itu. Ini bisa sangat berguna ketika pembaca hanya mencoba untuk mendapatkan inti umum, tetapi ada beberapa masalah:

  • Komentar tidak selalu benar, sedangkan kode melakukan apa yang dilakukannya. Jadi pembaca mengambil kata-kata Anda untuk itu, dan ini tidak ideal.
  • Pembaca belum memahami kode itu sendiri, jadi sampai mereka kembali lagi nanti, mereka masih belum memenuhi syarat untuk memodifikasi atau menggunakannya kembali. Dalam hal apa yang mereka lakukan membacanya?

Ada pengecualian, tetapi sebagian besar pembaca harus memahami kode itu sendiri. Komentar harus ditulis untuk membantu itu, bukan untuk menggantinya, itulah sebabnya Anda umumnya disarankan bahwa komentar harus mengatakan "mengapa Anda melakukannya". Seorang pembaca yang mengetahui motivasi untuk beberapa baris kode berikutnya memiliki peluang lebih baik untuk melihat apa yang mereka lakukan dan bagaimana.


5
Satu tempat yang berguna untuk komentar: dalam kode ilmiah, Anda seringkali dapat memiliki perhitungan yang cukup rumit, yang melibatkan banyak variabel. Untuk kewarasan programmer, masuk akal untuk membuat nama variabel sangat singkat, sehingga Anda dapat melihat matematika, bukan nama. Tetapi itu membuatnya sangat sulit untuk dipahami oleh pembaca. Jadi deskripsi singkat tentang apa yang sedang terjadi (atau lebih baik, referensi persamaan dalam artikel jurnal atau sejenisnya), bisa sangat membantu.
naught101

1
@ naught101: ya, terutama karena makalah yang Anda maksud juga mungkin menggunakan nama variabel satu huruf. Biasanya lebih mudah untuk melihat bahwa kode tersebut memang mengikuti makalah jika Anda menggunakan nama yang sama, tetapi itu bertentangan dengan tujuan dari kode tersebut cukup jelas (justru dijelaskan oleh makalah ). Dalam hal ini, komentar di mana setiap nama didefinisikan, mengatakan apa arti sebenarnya, pengganti untuk nama-nama yang bermakna.
Steve Jessop

1
Ketika saya mencari sesuatu yang spesifik dalam kode (di mana kasus khusus ini ditangani?), Saya tidak ingin membaca dan memahami paragraf kode hanya untuk menemukan bahwa itu bukan tempat. Saya perlu komentar yang merangkum dalam satu baris apa yang dilakukan paragraf berikutnya. Dengan cara ini, saya akan dengan cepat menemukan bagian-bagian kode yang terkait dengan masalah saya dan melewatkan detail yang tidak menarik.
Florian F

1
@FlorianF: respons tradisional adalah bahwa nama variabel dan fungsi harus menunjukkan kira-kira tentang apa kode itu, dan karenanya membiarkan Anda membaca hal-hal yang tentu saja bukan tentang apa yang Anda cari. Saya setuju dengan Anda bahwa ini tidak selalu berhasil, tetapi saya tidak begitu setuju sehingga saya pikir semua kode perlu dikomentari untuk membantu pencarian atau membaca skim. Tapi Anda benar, itu adalah kasus di mana seseorang membaca kode Anda (semacam) dan tidak perlu memahaminya.
Steve Jessop

2
@Snowman Orang bisa melakukan itu dengan nama variabel. Saya telah melihat kode di mana variabel listOfApples berisi daftar Pisang. Seseorang menyalin kode yang memproses daftar Apel dan mengadaptasinya untuk Pisang tanpa repot mengubah nama variabel.
Florian F

5

Seringkali kita harus melakukan hal-hal rumit. Memang benar untuk mendokumentasikannya untuk pemahaman di masa depan. Kadang-kadang tempat yang tepat untuk dokumentasi ini adalah dalam kode, di mana dokumentasi dapat tetap diperbarui dengan kode. Tapi itu pasti layak dipertimbangkan dokumentasi terpisah. Ini juga bisa lebih mudah disajikan kepada orang lain, termasuk diagram, gambar berwarna, dan sebagainya. Maka komentarnya adalah:

// This code implements the algorithm described in requirements document 239.

atau bahkan adil

void doPRD239Algorithm() { ...

Tentunya orang senang dengan fungsi yang bernama MatchStringKnuthMorrisPrattatau encryptAESatau partitionBSP. Lebih banyak nama yang tidak jelas perlu dijelaskan dalam komentar. Anda juga bisa menambahkan data bibliografi dan tautan ke sebuah makalah tempat Anda menerapkan algoritma.

Jika suatu algoritma itu kompleks dan baru dan tidak jelas, itu pasti bernilai dokumen, bahkan jika hanya untuk sirkulasi internal perusahaan. Periksa dokumen ke dalam kontrol sumber jika Anda khawatir dokumen itu hilang.

Ada kategori kode lain yang tidak terlalu algoritmik seperti birokratis. Anda perlu mengatur parameter untuk sistem lain, atau beroperasi dengan bug orang lain:

/* Configure the beam controller and turn on the laser.
The sequence is timing-critical and this code must run with interrupts disabled.
Note that the constant 0xef45ab87 differs from the vendor documentation; the vendor
is wrong in this case.
Some of these operations write the same value multiple times. Do not attempt
to optimise this code by removing seemingly redundant operations.
*/

2
Saya akan berdebat menentang penamaan fungsi / metode setelah algoritma internal mereka, sebagian besar waktu metode yang digunakan harus menjadi perhatian internal, dengan segala cara mendokumentasikan bagian atas fungsi Anda dengan metode yang digunakan, tetapi jangan menyebutnya doPRD239Algorithmyang memberitahu saya apa-apa tentang fungsi tanpa harus mencari algoritma, alasan MatchStringKnuthMorrisPrattdan encryptAESkerjanya adalah bahwa mereka mulai dengan deskripsi tentang apa yang mereka lakukan, kemudian menindaklanjuti dengan deskripsi metodologi.
scragar

5

Saya lupa di mana saya membacanya tetapi ada adalah garis tajam dan jelas antara apa yang harus muncul dalam kode Anda dan apa yang harus muncul sebagai komentar.

Saya percaya Anda harus mengomentari maksud Anda, bukan algoritma Anda . Yaitu berkomentar apa yang harus Anda lakukan, bukan pada apa yang Anda lakukan .

Sebagai contoh:

// The getter.
public <V> V get(final K key, Class<V> type) {
  // Has it run yet?
  Future<Object> f = multitons.get(key);
  if (f == null) {
    // No! Make the task that runs it.
    FutureTask<Object> ft = new FutureTask<Object>(
            new Callable() {

              public Object call() throws Exception {
                // Only do the create when called to do so.
                return key.create();
              }

            });
    // Only put if not there.
    f = multitons.putIfAbsent(key, ft);
    if (f == null) {
      // We replaced null so we successfully put. We were first!
      f = ft;
      // Initiate the task.
      ft.run();
    }
  }
  try {
    /**
     * If code gets here and hangs due to f.status = 0 (FutureTask.NEW)
     * then you are trying to get from your Multiton in your creator.
     *
     * Cannot check for that without unnecessarily complex code.
     *
     * Perhaps could use get with timeout.
     */
    // Cast here to force the right type.
    return (V) f.get();
  } catch (Exception ex) {
    // Hide exceptions without discarding them.
    throw Throwables.asRuntimeException(ex);
  }
}

Di sini tidak ada upaya untuk menyatakan apa yang dilakukan setiap langkah, semua yang dinyatakan adalah apa yang seharusnya dilakukan.

PS: Saya menemukan sumber yang saya maksud - Coding Horror: Code Tells You How, Komentar Tell You Why


8
Komentar pertama: Apakah sudah berjalan? Apa yang sudah berjalan? Sama untuk komentar lainnya. Untuk seseorang yang tidak mengetahui apa yang dilakukan kode, ini tidak berguna.
gnasher729

1
@ gnasher729 - Diambil keluar dari konteks hampir semua komentar tidak akan berguna - kode ini adalah demonstrasi menambahkan komentar yang menunjukkan niat daripada berusaha menggambarkan . Saya menyesal tidak melakukan apa pun untuk Anda.
OldCurmudgeon

2
Pemelihara kode itu tidak akan memiliki konteks. Ini tidak terlalu sulit untuk mengetahui apa yang dilakukan kode, tetapi komentar tidak membantu. Jika Anda menulis komentar, luangkan waktu Anda dan berkonsentrasi ketika Anda menulisnya.
gnasher729

BTW - Komentar Has it run yet mengacu pada Futuredan menunjukkan bahwa get()diikuti oleh cek terhadap nullmendeteksi apakah Futuresudah dijalankan - dengan benar mendokumentasikan maksud daripada proses .
OldCurmudgeon

1
@OldCurmudgeon: Balasan Anda cukup dekat dengan apa yang saya pikirkan, bahwa saya hanya akan menambahkan komentar ini sebagai contoh poin Anda. Sementara komentar tidak diperlukan untuk menjelaskan kode bersih, komentar yang baik untuk menjelaskan mengapa pengkodean dilakukan SATU JALAN LAIN. Dalam pengalaman saya yang terbatas, komentar sering berguna untuk menjelaskan keanehan dari kumpulan data yang dikerjakan oleh kode, atau aturan bisnis yang ditegakkan oleh kode tersebut. Kode komentar yang ditambahkan untuk memperbaiki bug adalah contoh yang baik, jika bug itu terjadi karena asumsi tentang data itu salah.
Randall Stewart

4

Tapi kita semua tahu itu tidak cukup.

Benarkah? Sejak kapan?

Kode yang dirancang dengan baik dengan nama-nama baik lebih dari cukup di sebagian besar kasus. Argumen yang menentang penggunaan komentar diketahui dan didokumentasikan (seperti yang Anda rujuk).

Tetapi ini adalah pedoman (seperti yang lainnya). Dalam kasus yang jarang terjadi (menurut pengalaman saya, kira-kira setiap 2 tahun sekali) di mana segala sesuatunya akan menjadi lebih buruk ketika direactored menjadi fungsi-fungsi yang lebih mudah dibaca (karena kebutuhan kinerja atau kohesi) kemudian lanjutkan - masukkan komentar panjang yang menjelaskan apa sebenarnya benda itu. lakukan (dan mengapa Anda melanggar praktik terbaik).


7
Saya tahu itu tidak cukup.
Florian F

2
Sejak kapan? Rupanya, Anda sudah tahu jawabannya. "Kode yang dirancang dengan baik dengan nama-nama baik lebih dari cukup di sebagian besar kasus." Jadi, itu mungkin tidak cukup dalam sebagian kecil kasus, yang persis apa yang diminta penanya.
Ellesedil

3
Saya pernah mencoba menguraikan kode orang lain yang saya inginkan telah menambahkan beberapa komentar lebih dari sekali setiap dua tahun.
Ogre Psalm33

@ OgrePsalm33 - Apakah mereka memiliki metode kecil dan menggunakan nama baik? Kode buruk itu buruk, terlepas dari komentar.
Telastyn

2
@Telastyn Sayangnya, ketika bekerja pada basis kode besar, metode "kecil" dan nama "baik" bersifat subyektif untuk masing-masing pengembang (demikian juga komentar yang baik, dalam hal ini). Seorang pengembang yang menulis kode algoritma pemrosesan grafik Flarbigan selama 7 tahun, dapat menulis sesuatu yang sangat jelas baginya dan pengembang yang serupa, tetapi akan samar bagi orang baru yang menghabiskan 4 tahun terakhir mengembangkan kode infrastruktur jaringan Perbian. Kemudian, 2 minggu kemudian, ahli Flarbigan berhenti.
Ogre Psalm33

2

Tujuan utama kode adalah memerintahkan komputer untuk melakukan sesuatu, jadi komentar yang baik tidak pernah menggantikan kode yang baik karena komentar tidak dapat dieksekusi.

Yang sedang berkata, komentar dalam sumber adalah salah satu bentuk dokumentasi untuk programmer lain (termasuk Anda). Jika komentar tentang masalah yang lebih abstrak daripada apa yang dilakukan kode pada setiap langkah, Anda melakukan lebih baik daripada rata-rata. Level abstraksi itu bervariasi dengan alat yang Anda gunakan. Komentar yang menyertai rutinitas bahasa majelis umumnya memiliki tingkat "abstraksi" yang lebih rendah daripada, misalnya, APL ini A←0⋄A⊣{2⊤⍵:1+3×⍵⋄⍵÷2}⍣{⍺=A+←1}⎕. Saya pikir itu mungkin pantas komentar tentang masalah yang ingin diselesaikan, hmmm?


2

Jika kode itu sepele, tidak perlu komentar penjelasan. Jika kodenya non-sepele, komentar penjelas kemungkinan besar juga akan non-sepele.

Sekarang, masalah dengan bahasa alami non-sepele adalah bahwa banyak dari kita tidak pandai membaca atau menulisnya. Saya yakin kemampuan komunikasi tertulis Anda luar biasa, tetapi seseorang yang kurang paham bahasa tulisan mungkin salah mengerti kata-kata Anda.

Jika Anda berusaha sangat keras untuk menulis bahasa alami yang tidak dapat disalahartikan, Anda akan berakhir dengan sesuatu seperti dokumen hukum (dan seperti yang kita semua tahu itu lebih verbal dan sulit dipahami daripada kode).

Kode harus menjadi deskripsi paling ringkas dari logika Anda, dan seharusnya tidak ada banyak perdebatan tentang arti kode Anda karena kompiler dan platform Anda memiliki pendapat akhir.

Secara pribadi saya tidak akan mengatakan bahwa Anda tidak boleh menulis komentar. Hanya Anda yang perlu mempertimbangkan mengapa kode Anda perlu komentar, dan bagaimana Anda dapat memperbaikinya. Ini sepertinya menjadi tema umum dalam jawaban di sini.


Persis apa yang saya pikirkan ketika saya tidak setuju dengan pernyataan "Seorang manusia dapat memahami sepotong bahasa Inggris jauh lebih cepat sehingga ia dapat memahami sepotong kode dengan makna yang sama (selama operasi tidak sepele)" Kode adalah selalu kurang ambigu dan lebih ringkas.
stephenbayer

0

Satu hal yang belum disebutkan adalah bahwa kadang-kadang mengomentari dengan tepat apa yang dilakukan sepotong kode dapat membantu dalam kasus-kasus di mana bahasa menggunakan sintaksis tertentu untuk berbagai keperluan. Misalnya, dengan asumsi semua variabel bertipe float, pertimbangkan:

f1 = (float)(f2+f3); // Force result to be rounded to single precision
f4 = f1-f2;

Pengaruh secara eksplisit casting floatuntuk floatadalah untuk memaksa hasil yang akan dibulatkan ke presisi tunggal; komentar dengan demikian dapat dilihat hanya dengan mengatakan apa yang dilakukan kode. Di sisi lain, bandingkan kode itu dengan:

thing.someFloatProperty = (float)(f2*0.1); // Divide by ten

Di sini, tujuan para pemain adalah untuk mencegah kompiler dari berkotek di cara komputasi yang paling efisien (f2 / 10) [ini lebih akurat daripada dikalikan dengan 0,1f, dan pada kebanyakan mesin lebih cepat daripada membaginya dengan 10.0f].

Tanpa komentar, seseorang yang meninjau kode sebelumnya mungkin berpikir para pemain ditambahkan dengan keyakinan yang keliru bahwa akan diperlukan untuk mencegah kompiler dari berkotek dan bahwa itu tidak diperlukan. Faktanya, para pemain berperan untuk melakukan persis apa yang dikatakan oleh spesifikasi bahasa: memaksa hasil perhitungan untuk dibulatkan ke presisi tunggal bahkan pada mesin di mana pembulatan akan lebih mahal daripada menjaga hasilnya dalam presisi yang lebih tinggi. Mengingat bahwa para pemain floatdapat memiliki sejumlah arti dan tujuan yang berbeda, memiliki komentar yang menentukan makna yang dimaksudkan dalam skenario tertentu dapat membantu memperjelas bahwa makna yang sebenarnya sejalan dengan maksud.


Saya tidak yakin bahwa J. Random Programmer, melihat contoh kedua, akan menyadari bahwa konstanta ditulis 0,1 untuk alasan yang baik, daripada karena programmer asli lupa mengetikkan 'f'.
David K

Terutama selama debugging, Anda tidak pernah berasumsi bahwa sesuatu telah dilakukan untuk alasan yang bagus.
gnasher729

@ Davidvid: Tujuan dari kode contoh kedua saya adalah untuk membandingkannya dengan potongan kode pertama. Dalam potongan kode kedua, niat programmer mungkin adalah untuk memiliki someFloatPropertyrepresentasi yang paling akurat dari f2/10yang ia dapat; tujuan utama dari pemeran kedua adalah hanya untuk membuat kompilasi kode . Dalam contoh pertama, bagaimanapun, para pemain jelas tidak diperlukan untuk tujuan normal (mengubah satu tipe waktu kompilasi ke yang lain) karena operan sudah float. Komentar berfungsi untuk membuat jelas bahwa para pemain yang dibutuhkan untuk tujuan sekunder (pembulatan).
supercat

Saya setuju dengan anggapan bahwa Anda tidak perlu berkomentar tentang (float)pemeran dalam contoh kedua. Pertanyaannya adalah tentang konstanta literal 0.1. Anda menjelaskan (dalam paragraf teks berikutnya) mengapa kami menulis 0.1: "lebih akurat daripada kalikan dengan 0,1f." Saya menyarankan agar itu adalah kata-kata yang seharusnya ada di komentar.
David K

@ DavidvidK: Saya pasti akan menyertakan komentar jika saya tahu bahwa 0.1f akan menjadi tidak tepat, dan akan menggunakan 0.1f jika saya tahu bahwa kehilangan presisi akan dapat diterima dan bahwa 0.1f sebenarnya secara material lebih cepat dari 0.1 . Jika saya tidak tahu salah satu dari hal-hal itu benar, lebih disukai kebiasaan pengkodean saya akan digunakan doubleuntuk konstanta atau perhitungan menengah yang nilainya mungkin tidak dapat direpresentasikan sebagai float[meskipun dalam bahasa yang membutuhkan gips double-to-float eksplisit yang menjengkelkan, kemalasan mungkin mendorong untuk menggunakan floatkonstanta bukan untuk kecepatan, tetapi untuk meminimalkan gangguan].
supercat

-1

Komentar yang menjelaskan apa yang dilakukan kode adalah bentuk duplikasi. Jika Anda mengubah kode lalu lupa memperbarui komentar, ini dapat menyebabkan kebingungan. Saya tidak mengatakan jangan menggunakannya, gunakan saja dengan bijaksana. Saya berlangganan pepatah Paman Bob: "Hanya komentar apa kode tidak bisa mengatakan".

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.