Apa itu kode yang mendokumentasikan diri dan dapatkah itu menggantikan kode yang terdokumentasi dengan baik? [Tutup]

Saya memiliki seorang kolega yang bersikeras bahwa kodenya tidak perlu komentar, itu "mendokumentasikan diri sendiri."

Saya telah meninjau kodenya, dan meskipun lebih jelas daripada kode yang saya lihat orang lain hasilkan, saya masih tidak setuju bahwa kode yang mendokumentasikan diri sendiri adalah lengkap dan berguna seperti kode yang dikomentari dan didokumentasikan dengan baik.

Membantu saya memahami nya sudut pandang.

• Apa itu kode yang mendokumentasikan diri
• Bisakah itu benar-benar menggantikan kode yang dikomentari dan didokumentasikan dengan baik
• Apakah ada situasi di mana lebih baik daripada kode yang didokumentasikan dan dikomentari dengan baik
• Adakah contoh-contoh di mana kode tidak mungkin didokumentasikan sendiri tanpa komentar

Mungkin itu hanya keterbatasan saya sendiri, tetapi saya tidak melihat bagaimana itu bisa menjadi latihan yang baik.

Ini tidak dimaksudkan sebagai argumen - tolong jangan mengemukakan alasan mengapa kode yang dikomentari dan didokumentasikan dengan baik adalah prioritas tinggi - ada banyak sumber daya yang menunjukkan ini, tetapi mereka tidak meyakinkan rekan saya. Saya percaya saya perlu lebih memahami perspektifnya untuk meyakinkannya sebaliknya. Mulai pertanyaan baru jika Anda harus, tetapi jangan berdebat di sini.

Wow, respon cepat! Harap baca semua jawaban yang ada dan berikan komentar untuk jawaban daripada menambahkan jawaban baru, kecuali jawaban Anda benar-benar berbeda dari setiap jawaban lainnya di sini.

Juga, Anda yang mendebat kode pendokumentasi diri - ini terutama untuk membantu saya memahami perspektif (yaitu, aspek positif) dari penginjil kode pendokumentasian diri. Saya berharap orang lain akan downvote Anda jika Anda tidak tetap pada topik.

Menurut pendapat saya, kode apa pun harus mendokumentasikan diri sendiri. Dalam kode yang didokumentasikan sendiri dan baik, Anda tidak perlu menjelaskan setiap baris karena setiap pengidentifikasi (variabel, metode, kelas) memiliki nama semantik yang jelas . Memiliki lebih banyak komentar daripada yang diperlukan sebenarnya membuat lebih sulit (!) Untuk membaca kode, jadi jika rekan Anda

• menulis komentar dokumentasi (Doxygen, JavaDoc, XML komentar dll) untuk setiap kelas, anggota, tipe dan metode DAN
• dengan jelas mengomentari bagian mana pun dari kode yang tidak mendokumentasikan diri DAN
• menulis komentar untuk setiap blok kode yang menjelaskan maksud, atau apa yang dilakukan kode pada tingkat abstraksi yang lebih tinggi (yaitu menemukan semua file lebih besar dari 10 MB alih-alih menelusuri semua file dalam direktori, uji apakah ukuran file lebih besar dari 10 MB, hasilkan kembali jika benar )

kode dan dokumentasinya baik-baik saja, menurut saya. Perhatikan bahwa kode yang didokumentasikan sendiri tidak berarti tidak boleh ada komentar, tetapi hanya bahwa tidak boleh ada komentar yang tidak perlu. Namun masalahnya adalah bahwa dengan membaca kode (termasuk komentar dan komentar dokumentasi) harus menghasilkan pemahaman langsung tentang apa yang kode lakukan dan mengapa. Jika kode "mendokumentasikan diri sendiri" membutuhkan waktu lebih lama untuk memahami daripada kode yang dikomentari, itu tidak benar-benar mendokumentasikan diri.

Nah, karena ini tentang komentar dan kode, mari kita lihat beberapa kode aktual. Bandingkan kode khas ini:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

Untuk kode dokumentasi diri ini, yang menunjukkan apa yang sedang dilakukan:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Dan kemudian untuk kode yang didokumentasikan ini, yang lebih baik menjelaskan mengapa hal itu dilakukan:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Dan versi terakhir dari kode sebagai dokumentasi dengan nol komentar diperlukan:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Berikut ini contoh gaya komentar yang buruk:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

Dalam contoh terakhir, komentar digunakan ketika variabel seharusnya dinamai secara deskriptif, dan hasil operasi diringkas ketika kita dapat dengan jelas melihat apa operasi itu. Saya lebih suka contoh kedua yang didokumentasikan sendiri untuk ini setiap hari, dan mungkin itulah yang teman Anda bicarakan ketika dia mengatakan kode yang didokumentasikan sendiri.

Saya akan mengatakan bahwa itu tergantung pada konteks apa yang Anda lakukan. Bagi saya, kode yang didokumentasikan sendiri mungkin cukup dalam hal ini, tetapi komentar yang merinci metodologi di balik apa yang dilakukan di belakang (dalam contoh ini, persamaan) juga berguna.

Kode itu sendiri akan selalu menjadi penjelasan terbaru tentang apa yang dilakukan kode Anda, tetapi menurut pendapat saya sangat sulit untuk menjelaskan maksud , yang merupakan aspek paling vital dari komentar. Jika ini ditulis dengan benar, kita sudah tahu apa yang dilakukan kode, kita hanya perlu tahu mengapa itu melakukannya!

Seseorang pernah berkata

1) Hanya menulis komentar untuk kode yang sulit dimengerti.
2) Cobalah untuk tidak menulis kode yang sulit dimengerti.

Gagasan di balik kode "self-documenting" adalah bahwa logika program aktual dalam kode itu cukup jelas untuk dijelaskan kepada siapa saja yang membaca kode tidak hanya apa yang dilakukan kode tetapi mengapa ia melakukannya.

Menurut pendapat saya, gagasan tentang kode yang mendokumentasikan diri sendiri adalah mitos. Kode dapat memberi tahu Anda logika di balik apa yang terjadi, tetapi tidak dapat menjelaskan mengapa itu dilakukan dengan cara tertentu, terutama jika ada lebih dari satu cara untuk menyelesaikan masalah. Untuk alasan itu saja tidak dapat menggantikan kode yang dikomentari dengan baik .

Saya pikir itu relevan untuk mempertanyakan apakah baris kode tertentu mendokumentasikan diri, tetapi pada akhirnya jika Anda tidak memahami struktur dan fungsi sepotong kode maka sebagian besar waktu komentar tidak akan membantu. Ambil, misalnya, irisan kode "komentar yang benar" dari amdfan:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Kode ini baik-baik saja, tetapi berikut ini sama-sama informatif di sebagian besar sistem perangkat lunak modern, dan secara eksplisit mengakui bahwa menggunakan perhitungan Newtonian adalah pilihan yang dapat diubah jika beberapa paradigma fisik lainnya lebih tepat:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

Dalam pengalaman pribadi saya, ada beberapa situasi pengkodean "normal" di mana Anda benar-benar membutuhkan komentar. Seberapa sering Anda akhirnya menggulirkan algoritme Anda sendiri, misalnya? Pada dasarnya segala sesuatu yang lain adalah masalah penataan sistem Anda sehingga pembuat kode dapat memahami struktur yang digunakan dan pilihan yang mendorong sistem untuk menggunakan struktur tertentu.

Saya lupa dari mana saya mendapat ini, tetapi:

Setiap komentar dalam suatu program seperti permintaan maaf kepada pembaca. "Saya menyesal karena kode saya sangat buram sehingga Anda tidak dapat memahaminya dengan melihatnya". Kita hanya harus menerima bahwa kita tidak sempurna tetapi berusaha untuk menjadi sempurna dan terus meminta maaf ketika kita perlu.

Pertama-tama, senang mendengar bahwa kode kolega Anda sebenarnya lebih jelas daripada kode lain yang Anda lihat. Itu berarti bahwa dia mungkin tidak menggunakan "mendokumentasikan diri sendiri" sebagai alasan karena terlalu malas untuk berkomentar kodenya.

Kode self-documenting adalah kode yang tidak memerlukan komentar teks bebas untuk pembaca yang berpengetahuan untuk memahami apa yang dilakukannya. Misalnya, kode ini mendokumentasikan diri:

print "Hello, World!"

dan begitu juga ini:

factorial n = product [1..n]

dan begitu juga ini:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Sekarang, ide "pembaca informasi" ini sangat subyektif dan situasional. Jika Anda atau orang lain mengalami kesulitan mengikuti kode kolega Anda, maka ia sebaiknya mengevaluasi kembali idenya tentang pembaca informasi. Beberapa tingkat keakraban dengan bahasa dan perpustakaan yang digunakan harus diasumsikan untuk memanggil kode yang mendokumentasikan diri.

Argumen terbaik yang saya lihat untuk menulis "kode dokumentasi diri" adalah bahwa ia menghindari masalah komentar teks bebas yang tidak setuju dengan kode seperti yang tertulis. Kritik terbaik adalah bahwa sementara kode dapat menggambarkan apa dan bagaimana melakukannya dengan sendirinya, itu tidak dapat menjelaskan mengapa sesuatu dilakukan dengan cara tertentu.

Kode self-documenting adalah contoh yang baik dari "KERING" (Don't Repeat Yourself). Jangan menggandakan informasi dalam komentar yang, atau bisa, dalam kode itu sendiri.

Daripada menjelaskan untuk apa variabel digunakan, ganti nama variabelnya.

Alih-alih menjelaskan apa yang dilakukan cuplikan singkat kode, ekstrak kode ke dalam metode dan berikan nama deskriptif (mungkin versi singkat dari teks komentar Anda).

Daripada menjelaskan apa yang dilakukan tes yang rumit, ekstrak itu ke dalam metode juga dan berikan nama yang bagus.

Dll

Setelah ini, Anda berakhir dengan kode yang tidak memerlukan banyak penjelasan, itu menjelaskan sendiri, jadi Anda harus menghapus komentar yang hanya mengulang informasi dalam kode.

Ini tidak berarti Anda tidak memiliki komentar sama sekali, ada beberapa informasi yang tidak dapat Anda masukkan ke dalam kode seperti informasi tentang maksud ("mengapa"). Dalam kasus ideal, kode dan komentar saling melengkapi, masing-masing menambahkan nilai penjelas yang unik tanpa menduplikasi informasi yang lain.

kode self-documenting adalah praktik yang baik dan jika dilakukan dengan benar dapat dengan mudah menyampaikan makna kode tanpa membaca terlalu banyak komentar. terutama dalam situasi di mana domain dipahami dengan baik oleh semua orang di tim.

Karena itu, komentar dapat sangat membantu bagi pendatang baru atau penguji atau untuk menghasilkan file dokumentasi / bantuan.

kode self-documenting + komentar yang diperlukan akan sangat membantu orang-orang di seluruh tim.

Dalam urutan:

• Kode self-documenting adalah kode yang dengan jelas menyatakan maksudnya kepada pembaca.
• Tidak semuanya. Komentar selalu membantu untuk komentar tentang mengapa strategi tertentu dipilih. Namun, komentar yang menjelaskan apa yang dilakukan bagian kode adalah indikasi kode yang tidak cukup mendokumentasikan diri sendiri dan dapat menggunakan beberapa refactoring ..
• Komentar berbohong dan menjadi ketinggalan zaman. Kode selalu mengatakan lebih cenderung mengatakan yang sebenarnya.
• Aku belum pernah melihat kasus di mana apa kode tidak bisa dibuat cukup jelas tanpa komentar; namun, seperti yang saya katakan sebelumnya, terkadang perlu / membantu untuk menyertakan komentar tentang alasannya .

Penting untuk dicatat, bahwa kode yang benar-benar mendokumentasikan diri membutuhkan banyak disiplin diri dan tim. Anda harus belajar memprogram dengan lebih deklaratif, dan Anda harus sangat rendah hati dan menghindari kode "pintar" yang mendukung kode yang begitu jelas sehingga sepertinya ada yang bisa menulisnya.

Ketika Anda membaca "kode dokumentasi diri", Anda melihat apa yang dilakukannya, tetapi Anda tidak selalu dapat menebak mengapa hal itu dilakukan dengan cara tertentu.

Ada banyak kendala non-pemrograman seperti logika bisnis, keamanan, permintaan pengguna, dll.

Ketika Anda melakukan pemeliharaan, informasi backgorund itu menjadi sangat penting.

Hanya sejumput garam saya ...

Untuk satu, pertimbangkan cuplikan berikut:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Dalam contoh ini Anda memiliki 5 baris komentar per 3 baris kode. Lebih buruk lagi - komentar tidak menambahkan apa pun yang tidak dapat Anda lihat dengan membaca kode. Jika Anda memiliki 10 metode seperti ini, Anda bisa mendapatkan 'kebutaan komentar' dan tidak memperhatikan satu metode yang menyimpang dari pola.

Jika tentu saja, versi yang lebih baik adalah:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Namun, untuk kode sepele saya lebih suka tidak memiliki komentar. Maksud dan keseluruhan organisasi lebih baik dijelaskan dalam dokumen terpisah di luar kode.

Perbedaannya adalah antara "apa" dan "bagaimana".

• Anda harus mendokumentasikan "apa" yang dilakukan rutin.
• Anda tidak boleh mendokumentasikan "bagaimana" melakukannya, kecuali kasus khusus (mis. Merujuk ke makalah algoritma tertentu). Itu harus didokumentasikan sendiri.

Satu hal yang mungkin ingin Anda tunjukkan kepada kolega Anda adalah tidak peduli seberapa mendokumentasi diri kodenya, jika pendekatan alternatif lain dipertimbangkan dan dibuang bahwa informasi akan hilang kecuali dia berkomentar kodenya dengan informasi itu. Terkadang penting juga untuk mengetahui bahwa suatu alternatif dipertimbangkan dan mengapa diputuskan menentang dan komentar kode kemungkinan besar akan bertahan seiring waktu.

Di sebuah perusahaan tempat saya bekerja, salah satu pemrogram menempel di bagian atas monitornya.

"Dokumentasikan kodemu seperti orang yang merawatnya adalah maniak pembunuh yang tahu di mana kamu tinggal."

kode self-documenting biasanya menggunakan nama variabel yang cocok persis dengan apa yang dilakukan kode sehingga mudah untuk memahami apa yang sedang terjadi

Namun, "kode dokumentasi diri" semacam itu tidak akan pernah menggantikan komentar. Terkadang kode terlalu kompleks dan kode yang didokumentasikan sendiri tidak cukup, terutama dalam hal pemeliharaan.

Saya pernah memiliki seorang profesor yang sangat percaya pada teori ini. Sebenarnya hal terbaik yang saya ingat pernah dia katakan adalah "Komentar adalah untuk banci"
Awalnya kami semua terkejut tapi itu masuk akal.
Namun, situasinya adalah meskipun Anda mungkin dapat memahami apa yang terjadi dalam kode tetapi seseorang yang kurang berpengalaman bahwa Anda mungkin datang di belakang Anda dan tidak mengerti apa yang sedang terjadi. Inilah saat komentar menjadi penting. Saya tahu berkali-kali bahwa kami tidak percaya itu penting tetapi ada sangat sedikit kasus di mana komentar tidak perlu.

Saya terkejut bahwa tidak ada yang membawa " Literate Programming ", sebuah teknik yang dikembangkan pada tahun 1981 oleh Donald E. Knuth dari TeX dan ketenaran "The Art of Computer Programming".

Premisnya sederhana: karena kode harus dipahami oleh manusia dan komentar dibuang begitu saja oleh kompiler, mengapa tidak memberi semua orang hal yang mereka butuhkan - deskripsi teks lengkap tentang maksud kode, tidak terkekang oleh persyaratan bahasa pemrograman , untuk pembaca manusia dan kode murni untuk kompiler.

Alat Pemrograman Literate melakukan ini dengan memberi Anda markup khusus untuk dokumen yang memberi tahu alat bagian mana yang harus menjadi sumber dan apa itu teks. Program kemudian merobek bagian kode sumber dari dokumen dan merakit file kode.

Saya menemukan contoh di webnya: http://moonflare.com/code/select/select.nw atau versi HTML http://moonflare.com/code/select/select.html

Jika Anda dapat menemukan buku Knuth di atasnya di perpustakaan (Donald E. Knuth, Programming Literate, Stanford, California: Pusat Studi Bahasa dan Informasi, 1992, Catatan Kuliah CSLI, no. 27.) Anda harus membacanya.

Itu kode dokumentasi diri, lengkap dengan alasan dan semuanya. Bahkan membuat dokumen yang bagus, Semua yang lain adalah komentar yang ditulis dengan baik :-)

Saya ingin menawarkan satu perspektif lagi ke banyak jawaban yang valid:

Apa itu kode sumber? Apa itu bahasa pemrograman?

Mesin tidak perlu kode sumber. Mereka senang menjalankan perakitan. Bahasa pemrograman adalah untuk keuntungan kita. Kami tidak ingin menulis rakitan. Kita perlu memahami apa yang kita tulis. Pemrograman adalah tentang menulis kode.

Apakah Anda dapat membaca apa yang Anda tulis?

Kode sumber tidak ditulis dalam bahasa manusia. Sudah dicoba (misalnya FORTRAN) tetapi tidak sepenuhnya berhasil.

Kode sumber tidak dapat memiliki ambiguitas. Itu sebabnya kita harus meletakkan lebih banyak struktur di dalamnya daripada yang kita lakukan dengan teks. Teks hanya berfungsi dengan konteks, yang kita terima begitu saja ketika kita menggunakan teks. Konteks dalam kode sumber selalu eksplisit. Pikirkan "menggunakan" dalam C #.

Sebagian besar bahasa pemrograman memiliki redundansi sehingga kompiler dapat menangkap kita ketika kita tidak koheren. Bahasa lain menggunakan lebih banyak inferensi dan mencoba menghilangkan redundansi itu.

Ketikkan nama, nama metode, dan nama variabel tidak diperlukan oleh komputer. Mereka digunakan oleh kami untuk referensi. Compiler tidak mengerti semantik, itu untuk kita gunakan.

Bahasa pemrograman adalah jembatan linguistik antara manusia dan mesin. Itu harus dapat ditulis untuk kita dan dapat dibaca untuk mereka. Tuntutan sekunder adalah bahwa itu harus dibaca oleh kita. Jika kita pandai semantik jika diizinkan dan pandai menyusun kode, kode sumber harus mudah dibaca bahkan untuk kita. Kode terbaik tidak perlu komentar.

Tetapi kompleksitas mengintai di setiap proyek, Anda selalu harus memutuskan di mana menempatkan kompleksitas, dan unta mana yang harus ditelan. Itu adalah tempat untuk menggunakan komentar.

Kode dokumentasi diri adalah pilihan yang mudah keluar dari masalah, karena kode waktu, komentar, dan dokumentasi berbeda. Dan itu adalah faktor pendisiplinan untuk menulis kode yang jelas (jika Anda ketat pada diri Anda sendiri).

Bagi saya, ini adalah aturan yang saya coba ikuti:

• Kode harus semudah dan sejelas mungkin untuk dibaca.
• Komentar harus memberikan alasan untuk keputusan desain yang saya ambil, seperti: mengapa saya menggunakan algoritma ini, atau batasan yang dimiliki kode, seperti: tidak berfungsi ketika ... (ini harus ditangani dalam kontrak / pernyataan dalam kode) (biasanya dalam fungsi / prosedur).
• Dokumentasi harus mencantumkan penggunaan (konversi panggilan), efek samping, kemungkinan nilai pengembalian. Itu dapat diekstraksi dari kode menggunakan alat-alat seperti jDoc atau xmlDoc. Karena itu biasanya berada di luar fungsi / prosedur, tetapi dekat dengan kode yang dijelaskan.

Ini berarti bahwa ketiga cara mendokumentasikan kode hidup berdekatan dan karenanya lebih mungkin untuk diubah ketika kode berubah, tetapi tidak tumpang tindih dengan apa yang mereka ungkapkan.

Masalah sebenarnya dengan apa yang disebut kode dokumentasi diri adalah bahwa ia menyampaikan apa yang sebenarnya dilakukannya. Meskipun beberapa komentar dapat membantu seseorang memahami kode dengan lebih baik (mis., Langkah-langkah algoritma, dll.), Hal ini terlalu berlebihan dan saya ragu Anda akan meyakinkan rekan Anda.

Namun, yang benar-benar penting dalam dokumentasi adalah hal-hal yang tidak secara langsung terbukti dari kode: maksud yang mendasarinya, asumsi, dampak, keterbatasan, dll.

Mampu menentukan bahwa kode melakukan X dari pandangan sekilas adalah cara yang lebih mudah daripada dapat menentukan bahwa kode tidak melakukan Y. Dia harus mendokumentasikan ...

Anda dapat menunjukkan kepadanya contoh kode yang terlihat baik, jelas, tetapi tidak benar-benar mencakup semua basis input, misalnya, dan melihat apakah ia menemukannya.

Saya pikir kode dokumentasi diri adalah pengganti yang baik untuk berkomentar. Jika Anda memerlukan komentar untuk menjelaskan bagaimana atau mengapa kode itu seperti itu, maka Anda memiliki fungsi atau nama variabel yang harus dimodifikasi agar lebih jelas. Bisa jadi ke koder apakah dia akan membuat kekurangan dengan komentar atau mengubah nama beberapa variabel dan fungsi dan kode refactoring sekalipun.

Namun itu tidak dapat benar-benar menggantikan dokumentasi Anda, karena dokumentasi adalah apa yang Anda berikan kepada orang lain untuk menjelaskan cara menggunakan sistem Anda, daripada bagaimana hal itu dilakukan.

Sunting: Saya (dan mungkin orang lain) mungkin harus memiliki ketentuan bahwa aplikasi Digital Signal Processing (DSP) harus dikomentari dengan sangat baik. Itu terutama karena aplikasi DSP pada dasarnya adalah 2 untuk loop yang diumpankan dengan array nilai dan menambah / mengalikan / mengatakan nilai ... untuk mengubah program Anda mengubah nilai dalam salah satu array ... perlu beberapa komentar untuk mengatakan apa Anda lakukan dalam kasus itu;)

Saat menulis kode matematika, kadang-kadang saya merasa berguna untuk menulis komentar panjang, seperti esai, menjelaskan matematika, konvensi notasi yang digunakan kode, dan bagaimana semuanya cocok. Kita sedang berbicara ratusan baris dokumentasi, di sini.

Saya mencoba membuat kode saya sendiri sebagai mendokumentasikan diri, tetapi ketika saya kembali bekerja setelah beberapa bulan, saya benar-benar perlu membaca penjelasan untuk menjaga dari membuat hash keluar dari itu.

Sekarang, tentu saja tindakan ekstrem semacam ini tidak diperlukan untuk kebanyakan kasus. Saya pikir moral ceritanya adalah: kode yang berbeda membutuhkan jumlah dokumentasi yang berbeda. Beberapa kode dapat ditulis dengan sangat jelas sehingga tidak memerlukan komentar - jadi tulislah dengan jelas dan jangan gunakan komentar di sana!

Tetapi banyak kode memang membutuhkan komentar agar masuk akal, jadi tuliskan sejelas mungkin dan kemudian gunakan sebanyak mungkin komentar yang dibutuhkan ...

Saya berpendapat - seperti banyak dari Anda - bahwa untuk benar-benar mendokumentasikan diri, kode perlu menunjukkan beberapa bentuk niat. Tapi saya terkejut belum ada yang menyebutkan BDD - Behaviour Driven Development . Sebagian dari idenya adalah bahwa Anda memiliki tes otomatis (kode) yang menjelaskan maksud kode Anda, yang sangat sulit untuk dinyatakan sebaliknya.

Pemodelan domain yang bagus 
+ nama baik (variabes, metode, kelas) 
+ contoh kode (tes unit dari kasus penggunaan) 
= perangkat lunak yang mendokumentasikan diri 

Beberapa alasan mengapa komentar tambahan selain kode mungkin lebih jelas:

• Kode yang Anda lihat dihasilkan secara otomatis, dan karenanya setiap pengeditan pada kode tersebut mungkin akan musnah pada saat proyek dikompilasi
• Implementasi yang kurang langsung diperjualbelikan untuk keuntungan kinerja (membuka gulungan, membuat tabel pencarian untuk perhitungan yang mahal, dll.)

Semuanya akan sesuai dengan nilai tim dalam dokumentasinya. Saya akan menyarankan bahwa mendokumentasikan mengapa / maksud daripada yang penting dan ini tidak selalu ditangkap dalam kode dokumentasi diri. dapatkan / atur tidak jelas - tetapi perhitungan, pengambilan dll sesuatu dari mengapa harus diungkapkan.

Perhatikan juga perbedaan dalam tim Anda jika Anda berasal dari negara yang berbeda. Perbedaan dalam diksi dapat menyusup ke penamaan metode:

Pencarian Bisection

BinarySearch

BinaryChop

Tiga metode ini disumbangkan dari pengembang yang dilatih di 3 benua berbeda melakukan hal yang sama. Hanya dengan membaca komentar yang menggambarkan algoritme, kami dapat mengidentifikasi duplikasi di perpustakaan kami.

Bagi saya membaca kode yang membutuhkan komentar seperti membaca teks dalam bahasa yang saya tidak tahu. Saya melihat pernyataan dan saya tidak mengerti apa artinya atau mengapa - dan saya harus melihat komentar. Saya membaca frasa dan saya perlu mencari di kamus untuk memahami artinya.

Biasanya mudah untuk menulis kode yang mendokumentasikan sendiri apa yang dilakukannya. Untuk memberi tahu Anda mengapa demikian, komentar lebih cocok, tetapi bahkan di sini kode bisa lebih baik. Jika Anda memahami sistem Anda pada setiap level abstraksi, Anda harus mencoba mengatur kode Anda seperti

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Di mana nama metode mencerminkan niat Anda dan tubuh metode menjelaskan bagaimana Anda mencapai tujuan Anda. Anda tetap tidak dapat memberi tahu seluruh buku dalam judulnya, jadi abstraksi utama sistem Anda masih harus didokumentasikan, serta algoritma yang rumit, kontrak metode non-sepele, dan artefak.

Jika kode yang diproduksi rekan Anda benar-benar didokumentasikan sendiri - beruntunglah Anda dan dia. Jika Anda berpikir bahwa kode kolega Anda perlu komentar - perlu. Cukup buka tempat yang paling tidak sepele di dalamnya, baca sekali dan lihat apakah Anda memahami semuanya atau tidak. Jika kode didokumentasikan sendiri - maka Anda harus. Jika tidak - ajukan pertanyaan pada kolega Anda, setelah dia memberi Anda jawaban, tanyakan mengapa jawaban itu tidak didokumentasikan dalam komentar atau kode sebelumnya. Dia dapat mengklaim bahwa kode adalah dokumen diri untuk orang pintar seperti dia, tetapi dia tetap harus menghormati anggota tim lain - jika tugas Anda memerlukan pemahaman tentang kode dan kode-nya tidak menjelaskan kepada Anda semua yang perlu Anda pahami - perlu komentar.

Sebagian besar dokumentasi / komentar berfungsi untuk membantu pengembang / pengembang kode di masa mendatang sehingga membuat kode tersebut dapat dipertahankan. Lebih sering kita akhirnya kembali ke modul kita di lain waktu untuk menambahkan fitur baru atau mengoptimalkan. Pada saat itu akan lebih mudah untuk memahami kode hanya dengan membaca komentar daripada melangkah melalui banyak breakpoints. Selain itu saya lebih suka menghabiskan waktu untuk memikirkan logika baru daripada menguraikan yang sudah ada.

Saya pikir apa yang ia maksudkan adalah bahwa jika komentar menjelaskan apa yang dilakukan kode, harus ditulis ulang agar jelas maksudnya. Itulah yang dia maksudkan dengan mendokumentasikan kode diri. Seringkali ini bisa berarti hanya memecah fungsi panjang menjadi potongan-potongan logis yang lebih kecil dengan nama fungsi deskriptif.

Itu tidak berarti kode tidak boleh dikomentari. Ini berarti bahwa komentar harus memberikan alasan mengapa kode ditulis sebagaimana adanya.

Saya percaya bahwa Anda harus selalu berusaha untuk mencapai kode dokumentasi diri karena itu membuatnya lebih mudah untuk membaca kode. Namun, Anda juga harus pragmatis tentang berbagai hal.

Sebagai contoh, saya biasanya menambahkan komentar untuk setiap anggota kelas (saya menggunakan komentar dokumentasi untuk ini). Ini menggambarkan apa yang harus dilakukan anggota tetapi tidak bagaimana melakukannya. Saya menemukan bahwa ketika saya membaca kode, terutama kode lama, ini membantu saya mengingat dengan cepat untuk apa anggota tersebut dan saya juga merasa lebih mudah daripada membaca kode dan mengerjakannya, terutama jika aliran kode melompat sedikit. .

Ini hanya pendapat saya saja. Saya tahu banyak orang yang bekerja tanpa komentar sama sekali dan mengatakan bahwa mereka merasa ini bukan masalah. Namun, saya telah bertanya kepada seseorang tentang metode yang mereka tulis enam bulan sebelumnya dan mereka harus berpikir selama beberapa menit untuk memberi tahu saya dengan tepat apa yang dilakukannya. Ini bukan masalah jika metode ini dikomentari.

Akhirnya, Anda harus ingat bahwa komentar sama-sama bagian dari sistem sebagai kode. Ketika Anda refactor dan mengubah fungsionalitas, Anda juga harus memperbarui komentar Anda. Ini adalah salah satu argumen untuk tidak menggunakan komentar sama sekali karena mereka lebih buruk daripada tidak berguna jika mereka salah.