Apa yang salah dengan komentar yang menjelaskan kode kompleks?

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?

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.

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();
  

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.

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?

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\.
+\,\;\?\'\\\+&%\$#\=~_\-]+))*$

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.

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.

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.

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).

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.

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.
*/

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

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).

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?

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.

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.

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".