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?

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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

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.

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;
}

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.

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.

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

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.

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.

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