Kode Dokumentasi Mandiri Vs. Kode yang dikomentari


22

Saya telah mencari tetapi tidak menemukan apa yang saya cari, jangan ragu untuk menautkan saya jika pertanyaan ini sudah diajukan.

Awal bulan ini posting ini dibuat:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

Pada dasarnya, Anda adalah programmer yang buruk jika Anda tidak menulis komentar. Pendapat pribadi saya adalah bahwa kode harus deskriptif dan sebagian besar tidak memerlukan komentar kecuali jika kode tidak dapat menggambarkan diri.

Dalam contoh yang diberikan

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

Penulis mengatakan kode ini harus diberi komentar, pendapat pribadi saya adalah kode tersebut harus berupa panggilan fungsi yang deskriptif:

$extension = GetFileExtension($image_filename);

Namun dalam komentar seseorang benar-benar membuat saran itu:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

Penulis menjawab dengan mengatakan komentator itu "salah satu dari orang-orang itu", yaitu seorang programmer yang buruk.

Apa yang dilihat orang lain tentang Kode Uraian Pribadi vs Kode Komentar?


1
@ Péter - Saya memang melihatnya, tetapi saya lebih ingin mendapatkan pendapat pribadi orang-orang di antara keduanya, daripada mendefinisikan komentar sebagai bau kode atau tidak.
Phill

2
Saya menemukan artikel itu .... mengerikan untuk dibaca. Sangat menghina.
sevenseacat

@Karpie - Apakah saya :(
Phill

3
"Kenapa kamu programmer PHP yang jelek" Jawab: Karena kamu pemrograman di PHP.
Thomas Eding

Metode yang Anda sukai pada dasarnya menggunakan pemanggilan fungsi untuk mengomentari kode Anda. Mengapa tidak menggunakan komentar untuk itu? Fungsi harus digunakan hanya untuk kode yang dapat digunakan kembali. Saya pribadi benci harus mengikuti kode orang lain yang ditulis dengan cara ini karena alasan yang sama pernyataan GOTO itu jahat - Itu menciptakan kode spageti. Ini dibuat lebih baik oleh IDE modern, tetapi tidak setiap bahasa dan pemrogram dapat menggunakan IDE ini dan itu masih membingungkan. Jujur, saya setuju bahwa Anda harus mengomentari bagian kode yang tidak jelas sekilas - itu hanya membuat membaca kode Anda jadi lebih cepat dan mudah.
dallin

Jawaban:


46

Saya lebih suka menulis kode dokumentasi diri. Panduan untuk ini adalah Kode Bersih .

Ini tentu saja tidak berarti orang tidak boleh menggunakan komentar - mereka memiliki peran mereka, tetapi IMHO Anda harus menggunakannya dengan hati-hati. Ini jawaban saya sebelumnya di SO menjelaskan pemikiran saya tentang topik lebih terinci.

Tentu saja, seperti yang dicatat oleh @Niphra, selalu bernilai untuk memeriksa bahwa apa yang saya yakini bersih benar-benar dapat dimengerti oleh orang lain. Namun, ini juga masalah praktik. Kembali di uni saya menulis potongan kode samar hanya karena menggunakan nama aneh dan lucu untuk semua entitas kode, sesuai dengan keinginan saya. Sampai guru saya melempar kembali salah satu tugas saya, dengan sopan mencatat bahwa ia tidak dapat menentukan modul mana yang paling utama :-) Itu adalah pelajaran yang baik, jadi saya berusaha untuk fokus menulis kode yang lebih mudah dibaca sejak saat itu. Saat ini saya hampir tidak mendapatkan keluhan dari rekan satu tim.


Saya suka buku itu :)
Phill

Saya masih menemukan komentar yang berharga untuk mengekspresikan strategi yang digunakan, dan mereka yang ditolak (dengan alasan). Saya setuju bahwa komentar mikro umumnya tidak berguna.
Matthieu M.

9
Salah satu kutipan favorit saya dari Clean Code adalah bahwa setiap komentar adalah kegagalan untuk mengekspresikan diri Anda dalam kode.
Doval

6
@Doval: Filosofi yang menarik, setidaknya berkaitan dengan komentar tentang apa yang kode lakukan . Di sisi lain, beberapa komentar yang paling berguna adalah komentar tentang mengapa kode tidak melakukan sesuatu - sebuah konsep yang menurut saya bukan kode yang harus diekspresikan.
supercat

1
Sepenuhnya tidak setuju. Tidak ada jumlah penamaan yang akan sepenuhnya menggambarkan tujuan logika.
Ngarai Kolob

65

Anda tidak boleh mendokumentasikan apa yang dilakukan kode, tetapi Anda harus mendokumentasikan mengapa kode itu melakukannya.

Tidak ada jumlah trik penamaan yang akan mengekspos mengapa dan di mana, jadi Anda harus menambahkan komentar untuk menjelaskan tujuan dari berbagai bit kode.

Semua komentar lain dapat dengan aman dihilangkan.


3
+1 Contoh dalam artikel tertaut mengatakan "beri komentar dalam situasi apa pun di mana tujuan kode yang saya tulis tidak segera terlihat." - Hanya konyol untuk percaya bahwa kode itu sendiri dapat mengkomunikasikan tujuan , karena mesin itu sendiri tidak memiliki konsep tujuan. Contoh balasan: Kami memiliki bug di hampir semua perangkat lunak yang pernah ditulis, ini benar. Jika komputer mengerti tujuan ( mengapa ), itu hanya akan menolak untuk melakukan apa pun selain apa yang kita maksudkan, daripada dengan patuh menciptakan kembali apa / kapan / bagaimana / ke mana hal itu menyebabkan bug.
David Meister

Semua kode di dalam suatu fungsi harus ada di sana untuk memenuhi tujuan fungsi, yaitu apa yang dilakukannya, misalnya menulis beberapa teks ke file, fungsi "writeTo (String text, File file)". Jika beberapa kode memiliki tujuan yang berbeda, misalnya memeriksa prasyarat, seperti memverifikasi bahwa file itu ada DAN tidak jelas, maka mungkin ide yang lebih baik daripada komentar yang menulis fungsi baru, misalnya "checkWritable (File file)". Kualitas kode bukan daftar periksa dogmatis, tetapi jika perlu komentar, itu pertanda buruk , dan "mengapa" bukan alasan yang baik untuk membutuhkannya . Mengapa ayam itu menyeberang jalan?
Trylks

2
@Trylks Itu berfungsi untuk beberapa kasus tetapi tidak untuk semua. Bayangkan skenario ini: for (int i = 0; i < length/2;i++) { //if length is odd, the middle element should stay in place. Sekarang, ini bukan sesuatu yang jelas dari tujuan fungsi penutup, juga tidak bisa diperhitungkan dalam fungsinya sendiri. Jika Anda membiarkannya tanpa komentar, itu jelas buruk. Jadi, Anda menambahkan komentar untuk memperjelas maksud Anda.
biziclop

2
@Trylks Selain itu, bahkan jika kami mengambil contoh Anda, Anda memfaktorkan check out Anda ke sebuah metode dan menyebutnya, hebat. Sekarang yang harus Anda jelaskan adalah mengapa Anda perlu memeriksa apakah file dapat ditulisi. :)
biziclop

38

Saya sebenarnya tidak percaya pada kode yang menggambarkan diri. Ada lebih banyak kode yang dapat dibaca dan lebih sedikit kode yang dapat dibaca , tergantung pada bahasa, pengetahuan Anda tentang hal itu (sebagai penulis asli), pengetahuan tentang pria yang membacanya, dan fungsi kode. Tapi tidak, tetap saja ... harus dijelaskan dengan komentar singkat.

Yang jelas bagi saya sekarang, bahwa saya berada dalam area pemikiran itu mungkin tidak akan jelas bagi saya dalam setahun, ketika saya memikirkan sesuatu yang sama sekali berbeda dan perlu menggunakan bagian kode ini lagi.

Jadi, komentari kode Anda. Tidak setiap baris (ya ampun, tidak) tentu saja, tetapi berikan beberapa baris komentar di atas fungsi / subrutin / modul , atau bagian yang sangat rumit dan ceritakan secara singkat apa fungsinya. Anda akan berterima kasih pada diri sendiri dalam satu atau dua tahun.


Pernah ke sana, melakukan itu. "Kode yang kurang dapat dibaca" harus ditingkatkan menjadi kode yang terbaca dengan baik. Pengetahuan tentang suatu bahasa tidak terlalu diperhitungkan: Ketika tidak terbiasa dengan sintaksis, Anda harus mempelajarinya terlebih dahulu - terus terang, itulah dasar untuk menjadi seorang profesional. Mencoba menebus kode yang buruk dengan menambahkan komentar bukanlah ide yang bagus. Komentar tidak boleh pernah mencoba menggambarkan apa yang dilakukan kode. Komentar (umum) hanya dibenarkan jika Anda perlu memberi tahu alasannya dan bukan apa . Yang lainnya hanyalah kebisingan dan hal-hal tambahan yang tidak perlu untuk dipelihara.
Powerslave

PS, saya tahu saya agak 'zombie' :) Maaf untuk itu
Powerslave

Untuk menghindari kebingungan, saya berbicara tentang kasus biasa, ketika Anda tidak dipaksa untuk menulis kode buruk oleh persyaratan bisnis (misalnya kinerja luar biasa atau pas ke penyimpanan terbatas). Dalam kasus lain (jarang), Anda tidak punya pilihan selain meninggalkan komentar, agak meringankan beban korban berikutnya.
Powerslave

19

Untungnya, kedua kubu dalam diskusi ini diwakili di sini, dan argumen pro dan kontra untuk keduanya disebutkan.

Saya percaya kedua kubu memiliki argumen yang tumpang tindih, dan sebenarnya setuju pada sebagian besar dari mereka, hanya cara bagaimana mencapainya agak berbeda.

Argumen yang tumpang tindih

  • Kode harus dapat dibaca.
  • Komentar tidak boleh mengatakan hal yang persis sama dengan kode, tetapi berikan wawasan lebih lanjut jika diperlukan.
  • Semua nama variabel / fungsi harus diberikan pemikiran yang baik sehingga mereka memberikan representasi yang baik tentang apa yang mereka / lakukan.
  • Kode duplikat harus dicegah.

Sekarang, perbedaan utama adalah berapa banyak bobot yang diberikan pada beberapa argumen tersebut.

Kode yang menggambarkan sendiri

  • Komentar dapat menjadi usang, jadi minimalkan menggunakannya, karena komentar yang salah lebih buruk daripada tidak ada komentar.
  • Komentar adalah duplikasi kode. Segala sesuatu yang dapat ditulis dalam kode, harus ditulis dalam kode.

Lebih banyak komentar

  • Komentar lebih mudah dibaca daripada kode. Bahasa Inggris polos lebih baik dalam menggambarkan sesuatu.

  • Kode biasa sering menyebabkan ambiguitas yang harus dikomentari. Mencoba menggambarkan ini dalam kode, menghasilkan nama yang terlalu panjang. Selain itu, Anda selalu dihadapkan dengan informasi 'ekstra' ini yang hanya Anda perlukan saat pertama kali menjumpainya.

Saya percaya kedua kubu memiliki argumen yang sangat valid, tetapi Anda tidak harus panik mengikuti satu kubu, hanya karena itu memecahkan satu masalah.

Untuk menunjukkan, dalam buku Clean Code , kode dipecah menjadi banyak metode yang lebih kecil yang hanya dipanggil sekali. Metode dibuat dengan alasan tunggal untuk mendokumentasikan kode (dan TDD lebih mudah). Ini menghasilkan Function Hell . Kode ini kurang dapat dibaca daripada aslinya, dan saat refactoring, tidak ada pemikiran diberikan untuk merangkum kode yang dapat digunakan kembali.

Di sisi lain, Anda sering melihat API di mana setiap fungsi dikomentari, hanya karena 'komentar baik'. Hal-hal yang seharusnya dikomentari masih belum.


1
@Steven - "Di sisi lain, Anda sering melihat API di mana setiap fungsi dikomentari, hanya karena 'komentar baik'. Hal-hal yang seharusnya dikomentari tetap tidak." Ugh, benar sekali!
dss539

Ini jawaban yang sangat bagus! Satu hal, jika Anda tidak keberatan, pada keterbacaan komentar: Saya pribadi tidak percaya komentar lebih mudah dibaca. Kami, sebagai pengembang, biasanya berpikir dalam kode sumber, terutama ketika dalam "mode pengkodean". Pada saat-saat itu, ketidakjelasan bahasa manusia biasa biasanya lebih merupakan gangguan daripada bantuan.
Powerslave

5

"Aku minta maaf, tapi orangmu itu."

Saya heran mengapa dia tidak suka berkomentar: P

Serius, pengkodean adalah terlalu banyak seni yang orang bisa dengan jujur ​​membuat pernyataan yang menyapu. Terkadang Anda membutuhkan komentar, terkadang fungsi yang lebih banyak dan lebih baik. Biasanya keduanya.

Mencari pemrograman melek huruf sebagai gaya yang ekstrim.


Ya. Maksud saya, jika Donald Knuth berpikir Anda tidak hanya membutuhkan komentar, tetapi kadang-kadang membutuhkan bab - bab itu, saya akan berpikir setidaknya dua kali sebelum tidak setuju.
PeterAllenWebb

3

Jawaban Singkat, Lebih Baik, dan Benar

Gagasan bahwa yang Anda tulis, "kode yang didokumentasikan sendiri" adalah yang Anda butuhkan adalah anti-pola dan harus mati, bahkan ketika itu membuat pengecualian untuk komentar yang menjelaskan "mengapa". Ini adalah mitos bahwa Anda selalu dapat menulis semua kode untuk algoritma apa pun yang cukup jelas untuk dilirik oleh setiap programmer dan mendapatkannya (atau tidak memerlukan refactoring atau waktu organisasi yang tidak Anda miliki). Yang lebih penting, lebih sering daripada tidak, programmer yang berpikir mereka menulis kode yang jelas tidak.

Jawaban yang jauh lebih baik daripada komentar seharusnya hanya digunakan untuk menjelaskan "mengapa" adalah bahwa komentar harus:

  • jelaskan "mengapa" (tentu saja)
  • jelaskan "apa" pada masing-masing baris hanya ketika kodenya kompleks atau tujuannya tidak jelas dan tidak dapat atau tidak layak disederhanakan lebih lanjut
  • jelaskan "apa" untuk blok kode untuk mempercepat pemahaman dan menemukan apa yang Anda butuhkan

Penjelasan untuk Mencadangkannya

Orang keliru berpikir bahwa satu-satunya alasan orang menggunakan komentar adalah untuk menjelaskan apa arti sebaris kode. Yang benar adalah tujuan besar dari kode komentar adalah untuk membuatnya lebih cepatuntuk melirik kode Anda dan menemukan apa yang Anda cari. Ketika saya kembali ke kode nanti atau membaca kode orang lain, tentu saja, saya dapat membaca dan memahami bagian dari kode yang ditulis dengan baik - tetapi bukankah lebih cepat dan lebih mudah untuk membaca komentar di atas mengatakan apa yang dilakukan oleh bagian kode itu dan lewati sama sekali jika bukan itu yang saya cari? Mengapa duduk di sana dan mencari tahu kode sama sekali, bahkan jika itu ditulis dengan baik, jika Anda dapat melirik beberapa komentar dan memahami seluruh fungsi? Itu sebabnya kami menggunakan nama deskriptif untuk fungsi - tidak ada yang mengatakan saya tidak perlu menggunakan nama deskriptif untuk fungsi saya karena seseorang dapat melihat kode saya yang ditulis dengan rapi untuk melihat fungsinya.

Sebagai contoh, jika saya melihat melalui fungsi orang lain, apakah lebih mudah untuk pergi baris demi baris melalui kode untuk melihat apa yang dilakukannya atau untuk melirik tiga komentar yang ditulis dengan baik di seluruh fungsi untuk melihat dengan tepat apa yang dilakukan fungsi dan di mana sedang melakukannya?

Anti-pola lain adalah terlalu seringnya fungsi mengomentari kode Anda. Fungsi yang dinamai dengan baik adalah bagian penting dari dokumentasi kode, tetapi terkadang programmer memisahkan 2-3 baris kode yang tidak akan pernah digunakan di tempat lain menjadi fungsi untuk keperluan dokumentasi. Mengapa fungsi yang digunakan secara berlebihan lebih baik daripada menggunakan komentar yang berlebihan? Menggunakan fungsi seperti itu sama dengan merangkul pernyataan GOTO - itu menciptakan kode spaghetti yang bisa menyulitkan untuk diikuti.

Pada dasarnya, ketika Anda bekerja di lingkungan perusahaan, di mana orang-orang terus-menerus membagikan kode dan orang-orang tidak selalu punya waktu untuk membuat kode mereka sempurna, beberapa komentar yang baik dapat menghemat banyak waktu dan frustrasi. Dan ingat, walaupun Anda mungkin seorang guru yang dapat membaca kode dengan cepat, tidak semua orang di kantor Anda mungkin.


Saya benci ketika orang downvote dan bahkan tidak meninggalkan komentar mengapa. Apakah Anda bahkan membaca seluruh posting? Apa yang ada di sana tidak langsung dan benar? Apa yang tidak Anda setujui? Saya merasa orang-orang begitu tertarik pada ide mereka atau apa yang mereka baca sehingga mereka bahkan tidak memikirkannya dan akan segera membatalkan segala sesuatu yang tidak sesuai dengan pandangan mereka.
dallin

3
Saya berasumsi itu karena Anda langsung menolak dan menyebut sesuatu yang antipernah yang hampir secara universal diakui sebagai benar. Saya pikir Anda terlalu jauh. Sebagian besar, saya tidak bisa membayangkan memercayai komentar seperti halnya Anda. Jika Anda membabi buta membaca komentar dan bukan kode, komentar mungkin salah dan ketinggalan zaman, dan Anda tidak akan pernah tahu. Itulah dasar menggunakan fungsi sebagai dokumentasi. Saya setuju bahwa Anda seharusnya tidak memiliki terlalu banyak fungsi di satu tempat, meskipun solusi untuk itu jelas bukan untuk menggantinya dengan komentar.
Magus

@Magus Terima kasih atas komentarnya. Saya berasumsi Anda merujuk pada pembicaraan saya tentang menggunakan fungsi sebagai dokumentasi. Membaca ulang itu, saya percaya saya mengucapkannya dengan buruk terdengar seperti maksud saya menggunakan fungsi untuk tujuan itu sama sekali (sebagai lawan dari penggunaan fungsi yang berlebihan untuk tujuan itu) adalah buruk. Saya telah membersihkan paragraf itu untuk menjelaskan maksud asli saya. Pikiran saya tentang memercayai komentar adalah jika komentar menjadi usang, biasanya itu pertanda Anda berkomentar terlalu sempit pada bagian kode - bahwa Anda mengomentari implementasi dan bukan niat.
dallin

but isn't it faster and easier to read the comment at the top saying what that section of code does and skip it altogether if it's not what I'm looking forIni disebut "nama metode / fungsi". Jika Anda memiliki blok kode yang tidak memiliki nama tetapi sangat panjang sehingga Anda tidak dapat melihatnya dengan sekali lirikan, mungkin masalahnya ada di sana.
biziclop

1
@ biziclop Lembur Saya jadi percaya bahwa argumen ini sebagian besar bersifat semantik, dan dalam praktiknya, kode kita akan terlihat serupa. Karena itu, dengan asumsi blok kode tidak digunakan di lebih dari satu tempat, saya tidak melihat perbedaan antara blok kode dengan komentar deskriptif pendek di bagian atas dan satu blok kode dengan nama fungsi deskriptif pendek di teratas. Mereka sama, kecuali seseorang tidak memiliki ruang. Keduanya bisa salah dan ketinggalan zaman. Satu-satunya perbedaan yang benar-benar saya lihat adalah kode lebih mudah dibaca dengan komentar karena Anda tidak harus mengikuti panggilan fungsi ke lokasi terpisah.
dallin

2

Yah Anda juga harus mengingat sesuatu yang jelas atau "mendokumentasikan diri sendiri" untuk Anda, mungkin tidak untuk orang lain ... Mungkin seseorang dengan kurang memahami fungsi tertentu. Jadi saya berkomentar tentang semuanya.


1
Bisakah Anda memberi contoh. Maksud saya memberi contoh dalam pertanyaan awal saya. "GetFileExtension" apa gunanya komentar "Mendapat ekstensi file dari file yang diberikan"? Metode tersebut telah menjelaskan apa yang harus dimasukkan ke dalam komentar. Jika metode itu bernama "GetExtension" maka komentar akan membantu dalam menjelaskan apa metode yang harus dilakukan, karena metode ini tidak menjelaskan sendiri.
Phill

+1 Ini adalah pertanyaan orang yang Anda kenal. Siapa yang cenderung menggunakan fungsi ini? Bagaimana Anda bisa membantu mereka? Apa nilai bantuan Anda? Apakah bernilai lebih dari menghabiskan sedikit waktu sekarang untuk menambahkan komentar? Dll. Dll.
PeterAllenWebb

2
@PeterAllenWebb: Tidak ada poin sama sekali untuk komentar itu. Itu tidak jauh berarti fungsi tidak boleh dikomentari; Itu harus. Apakah "ekstensi" termasuk titik atau tidak? Untuk apa nilai baliknya "foo"? ( null?? "") Untuk "foo."? Akankah lewat nullmenyebabkan pengecualian, atau akankah fungsi mengembalikan sesuatu (mungkin null)?
TJ Crowder

2

Nah, masalahnya dengan kode dokumentasi diri adalah bahwa dalam fungsi itu, Anda akan menemukan:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

yang cukup jelas ketika Anda memiliki nama fungsi karena hanya dua baris. Ketika segala sesuatunya menjadi lebih rumit, Anda harus membungkus setiap baris kode dalam suatu fungsi dengan nama deskriptif, atau menggunakan komentar jika perlu .

Saya tidak pernah mengerti mengapa itu harus menjadi atau atau masalah, bukan dan / dan. Ya, buat kode Anda sebanyak mungkin dengan mendokumentasikan diri sendiri, dan ya, tambahkan beberapa komentar ke bagian yang seharusnya tidak jelas.


Ya. Saya pikir Anda harus "dilatih" untuk berpikir itu harus satu atau yang lain dan bukan keduanya.
PeterAllenWebb

2

Komentar dan kode bersih yang didokumentasikan sendiri berbeda. Kode adalah tentang bagaimana melakukan sesuatu. Dan komentar harus mencakup bagian mengapa , yang tidak dapat dijelaskan dalam kode, apa pun bahasa Anda. Juga, jika bahasa Anda sangat terbatas dan Anda tidak punya kontrak, tidak ada spesifikasi statis, dan bahkan tidak ada pernyataan, komentar harus mencakup masalah batas kode Anda.


Dengan asumsi ada alasan untuk semuanya, itu harus dikomentari?
JeffO

Ya tepatnya. Itu sebabnya saya percaya bahwa cara terbaik untuk mengomentari kode Anda adalah pemrograman yang melek.
SK-logic

1

Dalam hal ini, mudah untuk membuat fungsi deskriptif. Tapi saya sudah membaca banyak kode yang dibuat oleh programmer yang percaya kode mereka mendokumentasikan diri, dan apa yang jelas bagi mereka benar-benar membingungkan bagi saya.

$ extension = GetFileExtension ($ image_name);

Untuk kembali ke contoh Anda, dapatkah saya mengirim serangkaian nama gambar ke sana, atau hanya mengambil satu gambar? Apakah mendukung jenis file apa pun, atau hanya sebagian saja? Apakah itu akan mengamankan string untuk saya, atau apakah saya harus melakukannya? Jika jenis file tidak ada, apakah ini memberi tahu saya?

Tentu saja, saya meregangkan yang ini sedikit. Tapi saya ingat seorang programmer yang percaya bahwa audio_bandwidth dan video_bandwidth adalah nama yang didokumentasikan sendiri; ternyata audio harus dinyatakan dalam byte dan video dalam kilobyte. Butuh banyak waktu untuk memikirkannya.


5
Kau banyak melakukan itu. Fungsi mendapatkan ekstensi nama file. Tidak lebih dan tidak kurang. Namanya mengatakan apakah dibutuhkan array atau tidak (jelas tidak). Saya tidak bisa memikirkan metode yang akan bergantung pada jenis file untuk mendapatkan ekstensi. Mengamankan string adalah satu-satunya yang mungkin digabungkan, tetapi saya tidak akan pernah mengharapkannya karena seperti yang diketahui oleh para pengguna PHP: semua input pengguna dicurigai, jadi amankan sebelum Anda menggunakannya.
Matt Ellen

2
@ Matt: "Jelas tidak" adalah indikasi bahwa Anda tidak melakukan pemeliharaan sangat sering. Menjadi eksplisit menghemat banyak head-scratching (dan RTFSource) di kemudian hari, dan juga mendokumentasikan apa yang diharapkan penulis asli . Apakah itu dalam komentar atau nama fungsi yang panjang tidak terlalu penting.
Donal Fellows

Mungkin contohnya adalah salah satu yang buruk untuk digunakan dalam pertanyaan ini, saya belum menyentuh PHP dalam sekitar 7 tahun, telah melakukan C # dan sedikit Jawa, jadi saya terbiasa memiliki IDE yang memberitahu saya jenis yang dikembalikan atau mendeklarasikan jenisnya.
Phill

1
@Donal Fellows: tertulis file, singular. Apa yang mendua tentang itu? Ini sepenuhnya eksplisit.
Matt Ellen

4
Fakta bahwa sekarang ada 7 tanggapan dari 4 orang yang membahas kejelasan atau panggilan fungsi tunggal menyarankan kepada saya bahwa Anda perlu menggunakan komentar . Ini juga menyoroti fakta bahwa penamaan yang akurat adalah bentuk seni itu sendiri.
Semut

1

Yang satu tidak mengecualikan yang lain. Meskipun kode Anda dikomentari sendiri, ada kalanya Anda mungkin perlu komentar reguler untuk menjelaskan mengapa kode komentar otomatis Anda melakukan apa yang dilakukannya.


Saya pikir ini termasuk dalam pendapat saya yang "kode harus deskriptif dan sebagian besar tidak memerlukan komentar kecuali kode tidak dapat menggambarkan diri sendiri". Jika Anda menulis kode yang ditulis dengan baik, tidak sepenuhnya menjelaskan maksud kode, maka komentar membantu membuat kode lebih deskriptif.
Phill

Kode tidak pernah bisa menjelaskan tujuannya. Ketika Anda melihat palu, Anda tidak tahu apa gunanya - apakah untuk menghancurkan tengkorak atau hanya untuk menempa besi mentah.
SK-logic

1
@ SK-logic:public <T> void hit(T item);
Michael K

@Michael - tepatnya. Bagaimana pengguna akan mengetahui, kategori objek apa yang dapat dan harus dipalu? Bahkan dengan sistem tipe yang jauh lebih baik tidak selalu jelas, rentang penggunaan apa yang sebenarnya direncanakan oleh pengembang.
SK-logic

1

Saya tidak setuju dengan artikel itu dan setuju dengan Anda sampai batas tertentu. Jika Anda menggunakan nama metode yang baik, nama variabel baik dan metode kecil yang melakukan satu hal, kode harus mudah diikuti.

Hanya berusaha untuk tidak menjadi pintar karena kode pintar dibaca dan dipelihara. Kata kunci: memelihara !

Pendapat saya adalah bahwa komentar harus menjelaskan mengapa dan bukan apa. Ingat dalam dunia hipotetis sempurna ini, kode Anda cukup bersih untuk memudahkan membaca, Anda tidak perlu menjelaskan apa yang dilakukannya, tetapi mengapa Anda memilih untuk melakukannya dengan cara ini atau itu.

Jika Anda menggunakan sistem kontrol sumber, Anda dapat menggunakan pesan komit untuk membuat semua orang (dan diri Anda sendiri) tahu apa yang Anda lakukan pada waktu tertentu dan yang lebih penting, why.a


1

Anda ingin menghindari menulis komentar sama seperti Anda ingin menghindari dokumentasi apa pun. Ketika datang ke bahasa pemrograman itu sendiri, semua orang beroperasi dari set kosakata dan sintaksis yang sama (hampir).

Saat aplikasi Anda untuk domain tertentu, mungkin sulit untuk membuat semua orang yang terlibat menyetujui dan / atau menetapkan kosa kata umum. Kita diajarkan untuk menghindari singkatan dan jargon yang luas, tetapi saya akan menyebutnya

EBITDA

dan tidak

EquitySebelumInterestTaxesDepresiasiAndAmortisasi

Jika Anda tidak tahu satu, Anda mungkin tidak mengerti yang lain. Jika perusahaan memiliki beberapa implementasi yang tidak biasa, komentar akan membantu programmer berikutnya yang mungkin memiliki pengalaman dalam domain, tetapi tidak pada perusahaan khusus ini (Yang hanya membuat segalanya lebih rumit.).


1

Saya pikir kita perlu membedakan antara dokumentasi dan ekspresifitas kode.

Saat men-debug atau meninjau kode, Anda tidak sedang membaca buku. Sebagian besar waktu Anda hanya ingin melompat dari metode ke metode dan membuat koneksi cepat di pikiran Anda untuk mendapatkan pemahaman dasar tentang apa yang terjadi pada saat runtime. Bukan dokumentasi di sekitar kode tetapi ekspresifitas dari tanda tangan kode yang penting dalam proses itu, kemampuan mereka untuk menjadi cukup bermakna sehingga Anda dapat segera mengidentifikasi mereka dan menambahkannya ke tumpukan panggilan internal Anda sendiri. Pada titik itu, otak kita (setidaknya, otakku bekerja seperti itu;)) cenderung menganggap blok komentar yang besar sebagai suara daripada bantuan. Oleh karena itu, komentar satu-baris, atau bahkan lebih baik, hanya metode deskriptif-diri dan nama-nama objek sudah cukup di sini.

Jika Anda ingin "membaca buku" dari kelas atau fitur tertentu, tempat yang jauh lebih baik untuk itu adalah dalam unit test. Tes unit yang dirancang dengan baik pada dasarnya menunjukkan niat dan jauh lebih mendokumentasikan (yaitu penjelasan, rinci) daripada blok komentar paling tebal karena mengandung 1 / harapan pada apa yang seharusnya dilakukan oleh kode ini dan 2 / kemampuan untuk memeriksa harapan ini terhadap kode nyata. Tes kelulusan seratus kali lebih andal daripada komentar apa pun dalam hal dokumentasi, karena itu membuktikan bahwa apa yang dinyatakannya benar.


1

Beberapa kode tidak didokumentasikan sendiri, dan memerlukan komentar dari sesama manusia yang mengerti dan menguji bagian itu. Apa yang saya miliki di bawah ini tidak cukup untuk memahaminya, saya pikir.

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

1

Saya biasanya lebih suka menulis kode self-documenting, dengan komentar di mana tidak jelas, karena saya pikir sebagian besar kode tidak akan sepenuhnya mendokumentasikan dirinya.


0

Di universitas, kami diajarkan untuk mengubah kata setiap baris kode dalam bahasa Inggris dengan cukup banyak komentar (mungkin hanya untuk membuat kami terbiasa memahami kode apa yang sebenarnya dilakukan, daripada hanya menyalin / menempelkan sesuatu dan berharap yang terbaik).

Secara pribadi, saya rasa itu mengacaukan kode Anda, membuatnya lebih mudah dibaca daripada hanya komentar atau hanya kode. Saya seorang C # coder dan satu-satunya komentar yang saya buat sepanjang waktu adalah blok komentar "triple-slash" yang ditafsirkan kembali ke dokumentasi IntelliSense. Jika saya merasa sangat bersalah tentang cara tertentu dalam melakukan sesuatu, atau itu terlihat sangat samar, saya akan memberikan penjelasan lebih lanjut, tapi hanya itu.

IMO: Kode yang mendokumentasikan diri sendiri adalah kode tempat nama variabel dan metode diberi nama yang bermakna dan kontekstual, sehingga mereka menggambarkan apa tujuannya.


0

Jika Anda telah meninjau kembali kode Anda beberapa kali dan masih belum menemukan cara untuk menjelaskan maksudnya kepada seseorang yang mengetahui domain tersebut. Tulis ulang fungsinya. Lagi pula itu tidak lebih dari 10-20 baris. Jika itu lagi menulis ulang fungsi lagian itu lama dan itu bagian dari mengapa itu tidak dapat dibaca :) bilas-ulangi

dan dalam kasus yang tidak mungkin masih belum jelas apa yang dilakukan kode dan Anda ingat untuk meminta bantuan rekan-rekan Anda. Baiklah. Kita semua berterima kasih telah membantu mengembangkan Linux karena ini adalah kode kernel yang Anda tulis, bukan? kalau tidak bilas-ulangi dari atas :)

Sederhananya jangan menulis komentar Anda. KODE mereka


0

Lihat Kode Selesaikan edisi 2, hal 128-129.

Abstrak Tipe Data akan menyelamatkan Anda dari teka-teki ini. Kode mendokumentasikan diri adalah cara untuk pergi. Komentar dapat bermanfaat, tetapi memiliki

entitas dunia nyata daripada implementasi tingkat rendah

Anda dapat menghindari menggunakan komentar.

Satu hal tentang komentar adalah bahwa Anda menulisnya sekali, tetapi Anda tidak melihatnya ketika Anda menerapkan fungsi, Anda hanya melihatnya ketika Anda mengubah fungsi.

Komentar benar-benar berguna ketika ditafsirkan oleh IDE dengan cara Delphi 2009+ atau JavaDoc bekerja, tapi itu lebih merupakan bahasa markup terstruktur, jadi dalam arti Anda sedang memprogram dokumentasi Anda, yang sangat cerdas.


0

Saya percaya pada mantra bahwa kode tidak mendokumentasikan dirinya sendiri, karena Anda bisa menjadi programmer terbaik di dunia (Ada), namun tidak mengerti apa-apa tentang apa yang sedang terjadi, tetapi jika Anda mendokumentasikan mengapa dan dalam jangka pendek bagaimana kode Anda melakukan apa yang dilakukannya, Anda akan membantu diri sendiri dan orang lain di masa depan.


0

Komentar harus dimiliki. Karena ketika Anda menulis kode, Anda menulis untuk kebutuhan Anda saat ini, tetapi juga untuk orang-orang di masa depan yang harus membaca kode Anda, mencari tahu apa yang Anda lakukan, dan mengapa, dan kemudian bagaimana membuat modifikasi untuk itu.

Jika Anda hanya mengingat ini, saat coding / pemrograman?

Bagaimana saya bisa membuatnya lebih mudah untuk memahami dan memodifikasi untuk coders masa depan dari kode ini yang sedang saya kerjakan, maka Anda akan melakukan pekerjaan dengan baik. Kegagalan itu, hanya membuat Anda sulit bagi orang lain untuk mengubah kode Anda, dan jangan membayangkan itu tidak akan terjadi, itu jarang terjadi ...

Di sebagian besar pekerjaan saya, saya selalu memodifikasi kode orang lain, dan ditulis dengan sangat buruk, tidak terdokumentasi dengan baik.

Jadi kebiasaan Anda memikirkan dokumen kode itu sendiri, hanya tidak melakukan uji tuntas.

Sebagai programmer, kita harus mempraktikkan disiplin diri yang mungkin tampak sepenuhnya bagi programmer yang tidak berpengalaman, tetapi harus memiliki kebiasaan, untuk menghindari semua pengalaman mengerikan yang kita miliki dengan kode orang lain. Atau bahkan melihat kode kita sendiri berbulan-bulan, bertahun-tahun kemudian.

Lihat http://thedailywtf.com mereka memiliki banyak cerita lucu tapi nyata tentang programmer yang tidak melakukan due diligence mereka ..

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.