it-swarm-id.com

Kode Dokumentasi Mandiri Vs. Kode yang dikomentari

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-3571

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?

22
Phill

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

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

Tentu saja, seperti yang dicatat oleh @Niphra, selalu bernilai untuk memeriksa kembali 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 dia tidak bisa menentukan modul mana yang paling utama :-) Itu pelajaran yang bagus, jadi saya berusaha untuk fokus menulis kode yang lebih mudah dibaca sejak itu. Saat ini saya hampir tidak mendapatkan keluhan dari rekan satu tim.

47
Péter Török

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.

66
biziclop

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

Apa yang jelas bagi saya sekarang, bahwa saya masuk bidang pemikiran it mungkin tidak akan jelas bagi saya dalam setahun, ketika saya memikirkan sesuatu yang sama sekali berbeda dan perlu menggunakan bagian dari kode 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 sulit dan ceritakan secara singkat apa fungsinya. Anda akan berterima kasih pada diri sendiri dalam satu atau dua tahun.

38
Rook

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

Komentar lainnya

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

  • Kode biasa sering menyebabkan ambiguitas yang harus dikomentari. Mencoba menjelaskan ini dalam kode, menghasilkan nama yang terlalu panjang. Selain itu, Anda selalu dihadapkan dengan informasi 'ekstra' ini yang hanya Anda butuhkan 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 Kode Bersih , kode dipecah menjadi berbagai 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 sudah dikomentari masih belum.

19
Steven Jeuris

"Aku minta maaf, tapi orangmu itu."

Saya bertanya-tanya 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.

5
vegai

Jawaban Singkat, Lebih Baik, dan Benar

Gagasan yang ditulis dengan baik, "kode yang didokumentasikan sendiri" adalah yang Anda butuhkan adalah anti-pola dan harus mati, datar ketika 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 dilihat oleh setiap programmer dan mendapatkannya (atau tidak memerlukan refactoring atau waktu organisasi yang tidak Anda miliki). Lebih penting lagi, 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 Mendukungnya

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 cepat untuk melihat-lihat 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 melihat 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 fungsi yang terlalu sering digunakan untuk 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.

3
dallin

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.

2
user6791

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 beberapa baris kode dalam suatu fungsi dengan nama deskriptif, atau menggunakan komentar jika perl.

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.

2
Joris Meys

Komentar dan kode bersih yang didokumentasikan sendiri berbeda. Kode adalah semua tentang bagaimana untuk melakukan sesuatu. Dan komentar harus mencakup bagian why, 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.

2
SK-logic

Dalam hal ini, mudah untuk membuat fungsi deskriptif. Tetapi saya sudah membaca banyak kode yang dibuat oleh programmer yang baik 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 berbagai 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 bisa didokumentasikan sendiri; ternyata audio harus dinyatakan dalam byte dan video dalam kilobyte. Butuh banyak waktu untuk memikirkannya.

1
DistantEcho

Satu tidak mengecualikan yang lain. Meskipun kode Anda berkomentar sendiri, ada kalanya Anda mungkin perlu komentar reguler untuk menjelaskan mengapa kode komentar sendiri melakukan apa yang dilakukannya.

1
gablin

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 di 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
Sergio

Saya pikir kita perlu membedakan antara dokumentasi dan ekspresivitas dari 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 mendokumentasikan sekitar kode tetapi ekspresivitas dari tanda tangan kode yang penting dalam proses itu, kemampuan mereka untuk menjadi bermakna cukup sehingga Anda dapat segera mengidentifikasi mereka dan menambahkannya ke tumpukan panggilan internal Anda sendiri. Pada titik itu, otak kita (paling tidak, milikku bekerja seperti itu;)) cenderung menganggap blok komentar 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 tes unit. Tes unit yang dirancang dengan baik pada dasarnya menunjukkan maksud dan banyak lagi mendokumentasikan (yaitu jelas, terperinci) daripada yang paling tebal dari blok komentar karena mengandung 1/harapan pada apa yang seharusnya dilakukan oleh kode ini dan 2/kemampuan untuk memeriksa harapan ini terhadap kode asli. Tes kelulusan seratus kali lebih andal daripada komentar apa pun dalam hal dokumentasi, karena itu membuktikan bahwa apa yang dinyatakannya benar.

1
guillaume31

Beberapa kode tidak didokumentasikan sendiri, dan memerlukan beberapa 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
Job

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.

1
Abbafei

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
JeffO

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, ketika 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. Jika gagal, Anda hanya menyulitkan orang lain untuk mengubah kode Anda, dan jangan bayangkan 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 a.r. untuk programmer yang tidak berpengalaman, tetapi harus memiliki kebiasaan, untuk menghindari semua pengalaman mengerikan yang kami alami dengan kode orang lain. Atau bahkan melihat kode kita sendiri berbulan-bulan, bertahun-tahun kemudian.

Lihat http://thedailywtf.com mereka punya banyak cerita lucu tapi nyata tentang programmer yang tidak melakukan uji tuntas mereka ..

0
crosenblum

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

Secara pribadi, saya rasa itu mengacaukan kode Anda, membuatnya kurang dapat dibaca daripada jika itu 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 melakukan sesuatu, atau itu terlihat sangat samar, saya akan memberikan penjelasan lebih lanjut, tapi hanya itu.

IMO: Kode self-documenting adalah kode di mana nama variabel dan metode diberi nama yang bermakna dan kontekstual, sehingga mereka menggambarkan apa tujuannya.

0
James Love

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 terlalu lama dan itulah 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
Rune FS

Lihat Kode Lengkap 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 mengimplementasikan fungsi tersebut, Anda hanya melihatnya ketika Anda mengubah fungsinya.

Komentar benar-benar berguna ketika ditafsirkan oleh IDE 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
Peter Turner

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
Coyote21