Standar pengkodean untuk kejelasan: komentar setiap baris kode?

Saya telah bekerja di toko-toko yang menghasilkan perangkat lunak yang sangat penting dan saya telah berurusan dengan aturan komentar yang dimaksudkan agar kode tersebut dapat dibaca dan berpotensi menyelamatkan nyawa. Dalam pengalaman saya meskipun persyaratan menjadi tugas yang mematikan otak untuk dicentang dari daftar periksa dan tidak membantu saya tetap fokus pada penulisan kode yang dapat dimengerti. Ini juga mengalihkan perhatian peer reviewer saya dari percakapan yang lebih bermakna dengan saya tentang bagaimana membuat kode lebih mudah dimengerti.

Saya juga menilai kode siswa yang tidak memiliki komentar dan melihat mengapa mereka harus ditandai karena mengabaikannya.

Saya mengerti bahwa menggunakan nama baik, menjaga struktur tetap sederhana, fungsi pendek, dan modul fokus akan membuat kode cukup dimengerti sehingga komentar dapat diminimalkan.

Saya juga mengerti bahwa komentar harus menjelaskan mengapa kode melakukan apa yang dilakukannya, bukan bagaimana.

Mengingat semua ini, apakah mungkin untuk menulis standar pengkodean yang baik yang menangkap ide ini? Orang yang akan relevan dalam tinjauan sejawat tetapi tidak akan berubah menjadi kegiatan daftar periksa tanpa berpikir yang menghasilkan catatan tidak lebih membantu daripada: "Anda lupa berkomentar di baris 42".

Contoh jenis kode yang mungkin diperlukan oleh aturan ini ketika diperlakukan sebagai baris dalam daftar periksa:

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

Jika dimungkinkan untuk mengekspresikan ini dengan benar dalam dokumen standar, dan mungkin tidak, saya ingin menangkap ide di sepanjang baris ini:

Pertimbangkan komentar untuk setiap baris, urutan, pernyataan, bagian, struktur, fungsi, metode, kelas, paket, komponen, ... kode. Selanjutnya pertimbangkan untuk mengubah nama dan menyederhanakan untuk menghilangkan segala kebutuhan untuk komentar itu sehingga Anda dapat menghapusnya. Lapor masuk sementara komentar jarang terjadi. Ulangi sampai batas waktu. Kemudian ulangi lagi

Jawaban Michael Durrant adalah IMHO tidak buruk, tetapi tidak secara harfiah menjawab pertanyaan (seperti yang ia akui sendiri), jadi saya akan mencoba memberikan jawaban yang tidak:

Saya juga mengerti bahwa komentar harus menjelaskan mengapa kode melakukan apa yang dilakukannya, bukan bagaimana.

Mengingat semua ini, apakah mungkin untuk menulis standar pengkodean yang baik yang menangkap ide ini?

Jelas Anda dapat menulis daftar periksa untuk ulasan kode Anda , yang berisi pertanyaan seperti

• "Jika ada komentar, apakah itu menjelaskan mengapa kode melakukan apa yang dilakukannya?"
• "Apakah setiap baris kode - dalam konteksnya - cukup jelas sehingga tidak memerlukan komentar, atau jika tidak, apakah disertai dengan komentar yang menutup celah itu? Atau (lebih disukai) dapatkah kode diubah sehingga tidak perlu komentar lagi? "

Jika Anda suka, Anda dapat menyebutnya "standar pengkodean" (atau tidak, jika Anda pikir istilah standar pengkodean harus disediakan untuk daftar aturan braindead, mudah dijawab jika dipenuhi atau tidak, bagaimana format kode) harus terlihat seperti, atau di mana mendeklarasikan variabel). Tidak ada yang menghalangi Anda untuk memfokuskan checklist Anda pada pertanyaan semantik , alih-alih menempuh rute yang mudah dan hanya memasukkan aturan formal ke dalamnya.

Pada akhirnya, Anda harus yakin bahwa tim Anda membutuhkan daftar periksa semacam itu. Untuk menerapkan pertanyaan seperti itu, Anda memerlukan programmer dengan pengalaman sebagai pengulas, dan Anda perlu mencari tahu apakah itu benar-benar akan meningkatkan keterbacaan kode dalam tim ahli. Tapi itu adalah sesuatu yang harus Anda kerjakan bersama dengan tim Anda.

Anti-pola utama yang mengarah ke kode berkualitas buruk dengan kurang jelas

btw pembaca, judul awalnya "komentar setiap baris kode?" dan Anda dapat membayangkan reaksi naluriah dari banyak dari kita, termasuk saya sendiri. Saya kemudian diberi judul yang lebih akurat lagi.

Pada awalnya, membaca pertanyaan Anda, saya pikir, duplikat hal-hal dalam komentar, tapi ok, mungkin jika Anda memiliki cukup banyak ulasan oleh banyak orang ... tapi sekali lagi: orang membuat kesalahan, gagal untuk melihat ketidakkonsistenan, dll. Dan seiring waktu akhirnya akan ada perbedaan. Pada refleksi saya pikir masalahnya jauh lebih besar:

Pengembang akan cenderung menulis kode yang lebih buruk. Mereka akan menggunakan lebih banyak nama dan struktur samar karena 'dijelaskan dalam komentar - lihat!'.

Mempertimbangkan:

living_room_set = tables + chairs.

Sekarang pertimbangkan:

set = tbls+chrs # Make the set equal to the table plus the chairs

Anda tidak hanya memiliki lebih banyak nama samar dan lebih banyak untuk membaca, Anda juga harus melihat bolak-balik, melihat kode, apa yang ditetapkan? lihat kiri di kode, lihat kanan di komentar, apa tbls, lihat kiri di kode, lihat kanan di komentar, apa chrs, lihat kanan di komentar. Ya!

Ringkasan

Kembangkan atau tingkatkan standar komentar jika Anda dipaksa dalam posisi Anda saat ini sebagai pengembang (Sebagai mantan pemrograman COBOL, saya benar-benar melihat yang besar!) Tetapi menghabiskan banyak waktu, energi, dan semangat untuk menentang komentar anti-komentar. pola menggunakan argumen:

• Kode dan Komentar saling tidak sinkron ketika hanya satu yang diubah

• Komentar dapat menggambarkan apa yang dipikirkan satu orang tetapi mungkin salah dan karenanya menutupi bug

• Kode menjadi lebih sulit dibaca

• Kode yang baik menjadi lebih sulit untuk ditulis

• Kecenderungan untuk menggunakan lebih banyak nama samar

• Karakter berlebihan untuk dibaca dalam kode dan komentar

• Editor yang berbeda menggunakan gaya yang berbeda

• Membutuhkan kecakapan bahasa Inggris yang lebih tinggi dari sekedar coding

• Membutuhkan waktu dan sumber daya dan mengurangi dari nilai jangka panjang *

Plus berdebat untuk kode yang lebih baik tanpa komentar seperti itu, - sebenarnya memiliki standar (!) - semua nama variabel harus full_english_words - ada satu! Jadi gunakan energi 'standar' itu menuju standar kode dan tes yang ditulis dengan baik.

Salah satu dari dua masalah yang sulit adalah penamaan hal - jangan lewati masalah dengan komentar.

Mengingat bahwa salah satu masalah lain adalah pengoptimalan prematur dan bahwa pengoptimalan secara umum dapat menyebabkan kode 'mengapa begini' dikaburkan, ini adalah salah satu area di mana komentar penjelasan untuk kode yang kelihatannya buruk mungkin bermanfaat meskipun peringatan di atas masih berlaku.

* kode hari esok

Saya tidak berpikir dokumen standar pengkodean adalah tempat untuk menentukan apa yang sudah masuk akal. Tujuan standar pengkodean adalah untuk menjamin konsistensi (dan menghindari pertengkaran) tentang masalah di mana orang yang berakal mungkin tidak setuju dan tidak ada satu jawaban yang jelas, misalnya konvensi penamaan, indentasi dll.

Mengomentari seperti dalam contoh Anda secara objektif tidak berguna dan mungkin disebabkan oleh pengembang yang tidak berpengalaman, atau pengembang yang bekerja dengan sistem pembangunan yang secara mekanis memeriksa keberadaan komentar (ide yang benar-benar buruk, tetapi ada). Dalam kedua kasus solusinya adalah pendidikan, mungkin melalui tinjauan kode.

Jika Anda mulai menambahkan semua jenis "praktik terbaik" ke standar pengkodean, Anda hanya akan mengulangi yang sudah dinyatakan dalam banyak buku. Cukup beli "Clean Code", "Code Complete" dan "The Pragmatic Programmer" kepada pengembang yang dimaksud, dan pertahankan standar kode Anda.

Ini tidak mungkin. Apa yang pada dasarnya Anda coba lakukan adalah memekanisasi penilaian yang baik.

Saat menulis perangkat lunak penting seperti untuk sistem medis pendukung kehidupan, sejumlah besar daftar periksa dan yang lainnya hampir tidak bisa dihindari. Bahkan tidak hanya orang pintar membuat kesalahan, banyak perangkat lunak untuk perangkat ini ditulis oleh orang-orang yang tidak pandai dalam pekerjaan mereka, sehingga 'sistem' harus dapat melindungi terhadap pekerjaan yang ceroboh, membuatnya aman di biaya pemasaran.

Pilihan terbaik Anda adalah meninggalkan Standar Pengkodean yang ketat untuk berkomentar dan memimpin tim dengan memberikan contoh. Tunjukkan komentar orang lain seperti apa dengan berusaha menghasilkan kode berkualitas baik yang dikomentari dengan tepat. Alih-alih mencoba menemukan cara terbaik untuk menggambarkan bagaimana menulis komentar (yang lebih sering daripada panggilan penilaian) tunjukkan kepada orang lain apa yang Anda maksud setiap hari dengan ulasan kode Anda sendiri. Ketika anggota lain membaca kode Anda, mereka akan mengikuti jika mereka merasa itu berguna. Dan jika mereka tidak bisa maka tidak ada Standar yang akan membantu mereka menulis komentar yang lebih baik untuk memulai.

Memperbarui

Respons saya dalam kutipan untuk penekanan:

Adalah keyakinan saya bahwa jawaban yang menyatakan bahwa komentar tidak boleh dialamatkan dalam Standar Pengkodean dan kemudian mendaftar serangkaian pertanyaan defensif untuk melawannya, adalah satu-satunya jawaban yang benar.

Masalahnya di sini adalah bahwa Standar Pengkodean hanya itu, Standar . Gagasan yang sangat subyektif tidak harus dalam Standar Pengkodean . Ini bisa berupa panduan Praktik Terbaik, tetapi panduan itu tidak dapat digunakan terhadap pengembang selama Tinjauan Kode. Menurut pendapat pribadi saya, Standar Pengkodean harus sedekat mungkin dengan Otomatis. Ada begitu banyak waktu yang terbuang dalam Tinjauan Kode untuk memperdebatkan penamaan, penspasian, tab, tanda kurung, komentar, dll. Ketika semua itu bisa otomatis. Bahkan jawabannya tentang tablesdan chairsbisa otomatis. LINT'ers memungkinkan kamus, Cek Kapitalisasi per konsep (Variabel, Fungsi, Metode, Kelas, dll.).

Bahkan pemeriksaan JavaDoc dapat diimplementasikan oleh Robot LINT'er sebelum Permintaan Tarik diterima. Banyak proyek Open Source melakukan hal yang tepat ini. Anda mengirimkan Permintaan Tarik Anda, kode ini dibuat dengan file Travis-CI, termasuk Analisis Statis, dan harus melewati semua Standar Pengkodean yang dapat dinyatakan secara objektif. Tidak ada manusia yang berdebat tentang 'melakukan hal yang salah' atau tidak 'memberikan nilai' dengan komentar, atau cara yang salah untuk menyebutkan variabel, et el. Diskusi-diskusi itu tidak memberikan nilai dan sebaiknya diserahkan kepada robot pihak ketiga yang dapat menerima beban terbesar dari pengkodean emosional kita.

Untuk benar-benar menjawab pertanyaan kita harus membahas cara menulis Standar yang membahas bagaimana menjawab pertanyaan berikut: Apakah komentar ini memberikan nilai? Standar Pengkodean tidak mungkin menentukan 'nilai' dari komentar. Untuk itu menjadi perlu bagi manusia untuk melalui daftar periksa itu. Hanya menyebutkan komentar dalam Standar Pengkodean membuat daftar periksa yang ingin dihindari oleh Poster Asli.

Itu sebabnya komentar biasanya tidak diproses oleh kompiler dan dihapus. Nilai mereka tidak dapat ditentukan. Apakah komentar dalam pertanyaan itu berharga; ya atau tidak?. Menjawab pertanyaan ini adalah NP-hard. Hanya manusia yang memiliki kesempatan untuk menjawabnya dengan benar, dan itupun hanya dapat dijawab pada saat dibacakan, oleh orang yang membacanya; di mana nilai komentar itu dipengaruhi oleh cuaca, kehidupan rumah tangganya, pertemuan terakhir yang baru mereka hadiri dan tidak berakhir dengan baik, waktu, jumlah kopi yang mereka miliki. Saya percaya gambarnya menjadi lebih jelas.

Bagaimana itu bisa diungkapkan dengan benar dalam Standar apa pun? Suatu Standar tidak berguna kecuali jika dapat diterapkan secara konsisten dan adil, di mana adil lebih tentang obyektifitas bukan emosional.

Saya berpendapat bahwa Standar Pengkodean harus tetap seobjektif mungkin. Variabel cara diberi nama IS objektif. Mereka dapat dengan mudah diperiksa terhadap kamus untuk ejaan yang tepat, struktur tata bahasa, dan casing. Apa pun di luar itu adalah "pertandingan kencing" yang dimenangkan oleh orang yang paling berkuasa atau dengan "pemukulan alis". Sesuatu yang saya, secara pribadi, berjuang dengan TIDAK melakukan.

Ketika saya berkomentar, saya selalu berkomentar berbicara kepada diri saya di masa depan sebagai orang ketiga. Jika saya kembali ke kode ini dalam 5 tahun, apa yang perlu saya ketahui? Apa yang akan membantu, apa yang akan membingungkan, dan apa yang akan ketinggalan zaman dengan kode? Ada perbedaan antara mendokumentasikan kode untuk menghasilkan API publik yang dapat ditelusuri dan kode komentar yang memberikan nilai kepada pihak ketiga yang tidak dikenal, bahkan jika pihak ketiga itu adalah Anda sendiri.

Ini tes lakmus yang bagus. Jika Anda satu-satunya di proyek. Anda tahu Anda akan menjadi satu-satunya di proyek ini. Apa yang akan ada dalam standar pengkodean Anda? Anda ingin kode Anda menjadi bersih, jelas, dan dapat dimengerti oleh diri Anda sendiri di masa depan. Apakah Anda memiliki ulasan kode dengan diri sendiri tentang mengapa Anda tidak memberikan komentar di setiap baris? Apakah Anda akan meninjau setiap komentar yang Anda buat pada 100 file yang Anda laporkan? Jika tidak, lalu mengapa memaksa orang lain?

Sesuatu yang saya yakini tidak terjawab dalam diskusi ini adalah bahwa Future You juga pengembang di proyek ini. Ketika bertanya tentang nilai, besok Anda juga adalah orang yang dapat memperoleh nilai dari komentar. Jadi ukuran tim, menurut saya tidak masalah. Pengalaman tim tidak masalah, itu terlalu sering berubah.

Tidak ada jumlah kode komentar yang meninjau hal ini menghentikan pembuat langkah agar tidak menabrak dan membunuh seorang pasien. Setelah Anda berbicara tentang komentar yang memengaruhi kode, kini Anda berbicara tentang kode, bukan komentar. Jika yang diperlukan hanyalah komentar yang hilang untuk membunuh seseorang, ada hal lain yang berbau dalam proses tersebut.

Solusi untuk jenis pengkodean yang ketat ini telah disediakan sebagai metodologi untuk menulis perangkat lunak itu sendiri. Dan itu tidak ada hubungannya dengan komentar. Masalah dengan komentar adalah bahwa mereka TIDAK berdampak pada cara produk akhirnya bekerja. Komentar terbaik di dunia tidak dapat mencegah perangkat lunak mogok saat tertanam di dalam pembuat langkah. Atau saat mengukur sinyal listrik dengan EKG portabel.

Kami memiliki dua jenis komentar:

Komentar yang Dapat Dibaca dengan Mesin

Gaya komentar seperti Javadoc, JSDoc, Doxygen, dll. Adalah semua cara berkomentar di antarmuka publik yang disediakan oleh seperangkat kode. Antarmuka itu hanya dapat digunakan oleh pengembang tunggal lainnya (Kode kepemilikan untuk tim dua orang), sejumlah pengembang yang tidak diketahui (misalnya JMS), atau untuk seluruh departemen. Kode ini dapat dibaca oleh proses otomatis yang kemudian menghasilkan cara membaca komentar yang berbeda, ala HTML, PDF, dan semacamnya.

Jenis komentar ini mudah dibuat standar untuk. Ini menjadi proses objektif untuk memastikan setiap metode, fungsi, kelas yang dapat dipanggil secara publik berisi komentar yang diperlukan. Tajuk, parameter, uraian, dll. el. Ini untuk memastikan bahwa tim lain mudah menemukan dan menggunakan kode tersebut.

Saya melakukan sesuatu yang terlihat gila, tetapi sebenarnya tidak

Komentar-komentar ini ada di sini untuk membantu orang lain melihat MENGAPA kode ini ditulis dengan cara tertentu. Mungkin ada kesalahan numerik dalam prosesor yang menjalankan kode dan selalu dibulatkan, namun pengembang biasanya berurusan dengan kode yang mengumpulkan. Jadi, kami berkomentar untuk memastikan bahwa pengembang yang menyentuh kode memahami mengapa konteks saat ini melakukan sesuatu biasanya tampak tidak masuk akal, tetapi pada kenyataannya ditulis seperti itu dengan sengaja.

Jenis kode inilah yang menyebabkan begitu banyak masalah. Biasanya tidak dihapus dan kemudian ditemukan oleh pengembang baru dan 'diperbaiki.' Dengan demikian merusak segalanya. Bahkan kemudian, komentar hanya ada untuk menjelaskan MENGAPA untuk tidak benar-benar mencegah sesuatu dari kerusakan.

Komentar tidak dapat diandalkan

Komentar pada akhirnya tidak berguna dan tidak dapat dipercaya. Komentar biasanya tidak mengubah cara program dijalankan. Dan jika mereka melakukannya, maka proses Anda menyebabkan lebih banyak masalah dari yang seharusnya. Komentar adalah renungan dan tidak pernah bisa apa pun kecuali. Kode adalah yang terpenting karena hanya itu yang diproses oleh komputer.

Ini mungkin terdengar asin, tapi bersabarlah. Manakah dari dua baris ini yang benar-benar penting?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

Dalam contoh ini, yang penting adalah bahwa kita tidak tahu apa 'n' itu, tidak ada pemeriksaan untuk n menjadi 0 DAN bahkan jika ada, tidak ada yang menghentikan pengembang dari menempatkan n = 0SETELAH cek untuk 0. Jadi, komentar tidak berguna dan tidak ada yang otomatis bisa menangkap ini. Tidak ada standar yang bisa menangkap ini. Komentar, sementara cantik (untuk beberapa) tidak berpengaruh pada hasil produk.

Pengembangan Berbasis Tes

Apa yang terjadi pada produk? Industri di mana kode yang ditulis benar-benar dapat menyelamatkan atau membunuh seseorang harus diperiksa dengan teliti. Ini dilakukan melalui ulasan kode, ulasan kode, pengujian, pengujian, ulasan kode, tes unit, tes integrasi, percobaan, pementasan, bulan pengujian, ulasan kode, dan uji coba satu orang, pementasan, ulasan kode, pengujian, dan mungkin akhirnya pergi ke produksi. Komentar tidak ada hubungannya dengan semua ini.

Saya lebih suka kode yang tidak memiliki komentar, memiliki spesifikasi, memiliki unit test yang memverifikasi spesifikasi, studi tentang hasil menjalankan kode pada perangkat produksi, kemudian kode yang terdokumentasi dengan baik yang belum pernah diuji, juga tidak memiliki apa pun untuk membandingkan kode terhadap.

Dokumentasi itu bagus ketika Anda mencoba mencari tahu MENGAPA seseorang melakukan sesuatu dengan cara tertentu, namun, saya telah menemukan selama bertahun-tahun bahwa dokumentasi biasanya digunakan untuk menjelaskan mengapa sesuatu 'pintar' dilakukan, padahal sebenarnya tidak perlu ditulis seperti itu.

Kesimpulan

Jika Anda bekerja di perusahaan yang MEMBUTUHKAN setiap baris dikomentari, saya GARANSI setidaknya dua insinyur perangkat lunak pada proyek tersebut telah menulis program dokumen otomatis dalam Perl, Lisp, atau Python yang menentukan gagasan umum tentang apa yang dilakukan oleh saluran tersebut. , lalu tambahkan komentar di atas baris itu. Karena ini mungkin dilakukan, itu artinya komentar tidak berguna. Cari teknisi yang telah menulis skrip ini untuk secara otomatis mendokumentasikan kode dan menggunakannya sebagai bukti mengapa 'Komentar pada Setiap Baris' membuang-buang waktu, tidak memberikan nilai, dan berpotensi menyakiti.

Di samping itu, saya sedang membantu seorang teman dekat dengan tugas pemrograman. Gurunya telah menetapkan persyaratan bahwa setiap baris harus didokumentasikan. Jadi saya bisa melihat dari mana proses pemikiran ini akan datang. Tanyakan kepada diri sendiri, apa yang Anda coba lakukan, dan apakah ini hal yang benar? Kemudian tanyakan pada diri sendiri; Apakah ada cara untuk 'memainkan' sistem dengan proses ini? Jika ada, apakah itu benar-benar menambah nilai? Seseorang tidak dapat secara otomatis menulis unit test yang menguji kode yang memenuhi spesifikasi tertentu, dan jika mereka bisa, itu tidak akan menjadi hal yang buruk.

Jika suatu perangkat harus bekerja dalam kondisi tertentu karena itu akan berada di dalam manusia, satu-satunya cara untuk memastikan itu tidak akan membunuh mereka adalah tahun pengujian, tinjauan sejawat, percobaan, dan kemudian TIDAK PERNAH mengubah kode lagi. Inilah sebabnya mengapa NASA masih menggunakan perangkat keras dan lunak yang lama. Ketika datang untuk hidup atau mati Anda tidak hanya 'membuat sedikit perubahan dan memeriksanya.'

Komentar tidak ada hubungannya dengan menyelamatkan nyawa. Komentar untuk manusia, manusia membuat kesalahan, bahkan ketika menulis komentar. Jangan percaya manusia. Ergo, jangan percaya pada komentar. Komentar bukanlah solusi Anda.

Ada dua hal berbeda yang Anda singgung ketika Anda berbicara tentang komentar. Mereka tidak sama, dan perbedaannya penting.

Dokumentasi memberi tahu Anda tentang potongan kode yang menghadap keluar - antarmuka.

Biasanya perkakas akan memungkinkan Anda untuk membacanya secara mandiri, artinya Anda tidak melihat kode yang mendasarinya secara bersamaan.

Semua antarmuka harus didokumentasikan (misalnya setiap metode, tidak termasuk metode pribadi), dan harus menggambarkan input, output, dan segala harapan, batasan, dll., Terutama hal-hal yang tidak dapat diungkapkan melalui kendala, tes, dll. ( Jumlah persisnya dan ke mana arahnya tergantung pada proyek).

Dokumentasi yang baik memungkinkan konsumen potensial untuk memutuskan apakah, kapan, dan bagaimana menggunakan kode.

Komentar dalam kode sumber memiliki tujuan berbeda. Mereka ada di sana untuk orang yang melihat kode sumber. Mereka terutama menggambarkan implementasinya.

Komentar selalu dibaca di antara kode yang mendasarinya.

Komentar harus menjelaskan keputusan mengejutkan atau algoritme kompleks, atau opsi yang tidak diambil (dan alasan). Mereka ada di sana sehingga pengembang masa depan dapat memahami proses pemikiran para pendahulu mereka, dan memiliki informasi yang mereka mungkin mengabaikan atau menghabiskan banyak waktu mencari, misalnya

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

Anda tidak dapat menyimpulkan apa pun dari tidak adanya komentar, dan komentar itu tentu saja salah seperti kode di sekitarnya atau lebih tepatnya. Penghakiman harus dilaksanakan baik pada bagian penulis dan pada bagian pembaca.

Mengomentari setiap baris jelas lebih banyak pekerjaan dari nilai tambahan yang dipertanyakan, yang datang dengan biaya peluang. Jika Anda memiliki aturan yang mengatakan setiap baris harus dikomentari, Anda akan mendapatkannya, tetapi dengan mengorbankan bagian-bagian penting yang dikomentari dengan baik .

Tapi itu lebih buruk dari itu: tujuan dari komentar dikalahkan jika setiap baris dikomentari. Komentar menjadi noise yang membuat kode sulit dibaca: mengaburkan daripada mengklarifikasi. Selain itu, komentar sembarangan membuat komentar yang benar-benar penting lebih sulit dikenali.

Baik komentar maupun dokumentasi tidak memberikan ukuran atau jaminan apa pun atas kualitas kode yang mereka jelaskan; mereka bukan pengganti untuk QA asli. Tujuan mereka berwawasan ke depan, yaitu dengan harapan bahwa mereka akan membantu mereka yang berinteraksi dengannya menghindari membuat kesalahan.

Singkatnya , standar pengkodean Anda dapat dan harus membutuhkan dokumentasi (pemeriksaan otomatis membantu menemukan fungsi / metode yang tidak berdokumen, tetapi manusia masih perlu memeriksa apakah dokumentasi itu bagus). Komentar adalah panggilan penilaian, dan panduan gaya Anda harus mengakui hal ini. Mereka yang tidak pernah berkomentar, dan mereka yang berkomentar tanpa berpikir harus berharap ditantang.

Anda tidak dapat menyusun standar komentar, karena Anda tidak bisa tahu apa komentar penting di muka.

Tetapi Anda masih ingin memastikan kode tersebut dikomentari dengan benar, karena ini adalah kode kritis kehidupan. Solusinya adalah memiliki standar untuk tinjauan kode - mengharuskan komentar ulasan kode pada pemahaman.

Ini tidak akan menjamin bahwa itu tidak akan berubah menjadi daftar periksa yang tidak berarti, tetapi setidaknya akan membuatnya dari membuat kode lebih sulit dibaca Dan memiliki kemungkinan membuatnya lebih baik.

Ini memerlukan budaya di mana tinjauan kode itu sendiri bukan isyarat yang tidak berarti, di mana mendapatkan kode Anda kembali sebagai sulit dibaca adalah hal yang baik, dan bukan penghinaan atau gangguan. Sama pentingnya, di mana mengatakan itu tidak jelas, tidak dilihat sebagai kegagalan pembaca.

Kode yang tidak dapat dibaca, sampai batas tertentu, tidak dapat dihindari. Karena penulis terbenam dalam konteksnya, dan akan melihat sesuatu yang jelas ketika itu hanya jelas jika Anda tahu x, y, atau z.

Jadi, Anda tidak akan dapat memiliki aturan yang mengatakan memberikan umpan balik yang baik, tetapi Anda dapat melihat ulasan. Bahkan manajer non-programmer dapat melakukannya - karena pertanyaan sebenarnya bukan adalah kode yang ditulis dapat dibaca, tetapi apakah kode tersebut benar-benar dapat dibaca, yang hanya dapat diputuskan oleh seseorang yang membacanya.

Komentari setiap baris kode? Tidak ada .

Tujuan dari aturan lain yang Anda bicarakan adalah untuk menghindari hal itu.

Komentar untuk kode yang dapat dibaca paling tidak berlebihan, dan paling buruk akan membuat pembaca tidak mencari tujuan komentar yang tidak ada.

Jika Anda berkomentar seluruh kode yang jelas, Anda menggandakan jumlah bacaan tanpa memberikan informasi tambahan. Saya tidak yakin apakah redundansi semacam itu akan membuahkan hasil. Orang dapat membayangkan pengulas mengatakan bahwa 42 mengatakan " display_error" sementara komentar mengatakan "menampilkan peringatan". Tapi bayangkan perubahan dalam kodenya. Anda memiliki dua tempat untuk diperbaiki sekarang. Menjadi jelas gaya ini memiliki copy-paste negatif.

Saya akan mengatakan bahwa secara optimal kode tidak perlu komentar, selain dokumentasi.

Ada gaya yang berlawanan total, jika Anda ragu tentang garis itu:

1. Kode ini terlalu rumit dan harus direactored menjadi fungsi dengan nama dengan makna semantik untuk bagian kode. Baik itu kompleks ifatau sebagian dari suatu algoritma. (Atau LINQ pintar satu-liner)

2. Jika tidak bisa disederhanakan, Anda tidak tahu cukup idiom bahasa.

(Saya pribadi bukan fanatik aturan ketat tanpa komentar, tapi saya menganggapnya sebagai pola pikir awal yang baik untuk dilewati.)

Mengingat semua ini, apakah mungkin untuk menulis standar pengkodean yang baik yang menangkap ide ini?

Adapun prosesnya. Standar kami memberikan cukup banyak kredit kepada pengulas. Dengan asumsi mereka tidak jahat ini berfungsi dengan baik.

Ketika dia bertanya "Apa itu variabel o?", Anda menamainya kembali. Jika dia bertanya apa yang dilakukan blok ini, apakah refactor atau komentar. Jika ada perdebatan apakah ada sesuatu yang jelas atau tidak, jika peninjau tidak mengerti, maka menurut definisi tidak. Pada kesempatan yang sangat jarang ada sesuatu seperti pendapat ke-2 dari beberapa teman.

Rata-rata, Anda harus mendapatkan kode yang bisa dimengerti oleh programmer rata-rata dalam tim. IMO mencegah informasi yang berlebihan, dan memastikan bahwa kode dapat dimengerti oleh setidaknya satu anggota tim lainnya, yang kami temukan optimal yang baik.

Juga, tidak ada yang absolut . Padahal kami adalah kelompok kecil. Sangat mudah untuk menemukan konsensus dalam kelompok 5.

Pertanyaan:

Mengingat semua ini, apakah mungkin untuk menulis standar pengkodean yang baik yang menangkap ide ini? Orang yang akan relevan dalam tinjauan sejawat tetapi tidak akan berubah menjadi kegiatan daftar periksa tanpa berpikir yang menghasilkan catatan tidak lebih membantu daripada: "Anda lupa mengomentari saluran 42".

Komentar hendaknya tidak berupaya mengedukasi pembaca tentang bahasa. Seorang pembaca harus dianggap tahu bahasa lebih baik daripada penulis, tetapi dengan konteks yang jauh lebih sedikit daripada penulis.

Pembaca kode ini, dari contoh Anda, harus tahu bahwa exit()akan keluar dari aplikasi - sehingga membuat komentar menjadi berlebihan:

/* Exit the application */
exit();

Komentar yang berlebihan adalah pelanggaran KERING, dan perubahan pada kode tidak selalu menyebar ke komentar, meninggalkan komentar yang tidak mencerminkan apa yang sebenarnya dilakukan oleh kode.

Namun, komentar yang menjelaskan mengapa Anda melakukan sesuatu mungkin berharga - terutama jika Anda tidak dapat dengan mudah mengomunikasikan makna dalam kode itu sendiri.

Python 8PP 8 (panduan gaya untuk Python di pustaka standar CPython) memberikan pedoman berikut untuk komentar sebaris:

Gunakan komentar sebaris dengan hemat.

Komentar inline adalah komentar di baris yang sama dengan pernyataan. Komentar sebaris harus dipisahkan oleh setidaknya dua spasi dari pernyataan. Mereka harus mulai dengan # dan satu spasi.

Komentar sebaris tidak perlu dan bahkan mengganggu jika mereka menyatakan yang jelas. Jangan lakukan ini:

x = x + 1                 # Increment x

Namun terkadang, ini berguna:

x = x + 1                 # Compensate for border

Dengan contoh seperti itu, saya pribadi lebih suka melangkah lebih jauh dan akan mencoba menghilangkan komentar ini juga. Misalnya, saya mungkin tiba di:

border_compensation = 1
compensated_x = x + border_compensation

Membuat kode Anda mendokumentasikan diri sendiri bukanlah ide baru .

Kembali ke pertanyaan aktual:

Mengingat semua ini, apakah mungkin untuk menulis standar pengkodean yang baik yang menangkap ide ini?

Saya percaya bahwa panduan dan contoh PEP 8 menunjukkan standar pengkodean yang baik yang menangkap gagasan ini. Jadi ya, saya percaya itu mungkin.

Saya pikir ketika Anda melihat komentar semacam ini, dan saya kadang-kadang menulis seperti ini, itu karena penulis menulis spesifikasi dalam komentar dan kemudian melalui dan menerapkan setiap komentar.

Jika kita ditantang untuk menulis standar pengkodean yang menghasilkan kode yang dapat dimengerti dalam hal fungsionalitas yang diperlukan daripada fungsionalitas sebenarnya (sehingga kesalahan dapat dilihat) maka apakah kita benar-benar berbicara tentang bagaimana spesifikasi didefinisikan, didokumentasikan dan dihubungkan ke produk akhir?

sunting ----

Hanya untuk mengklarifikasi. Saya tidak masuk ke komentar vs tdd vs unit test mana yang terbaik. Atau menyarankan komentar per baris adalah baik / buruk

Saya hanya menyarankan alasan Anda mungkin melihat gaya berkomentar dibicarakan dalam contoh.

Dan dari pertanyaan itu apakah standar pengkodean tentang komentar sebenarnya lebih baik ditulis sebagai persyaratan dokumen spesifikasi.

yaitu komentar untuk menjelaskan tujuan kode, yang juga merupakan spesifikasi

Mengingat semua ini, apakah mungkin untuk menulis standar pengkodean yang baik yang menangkap ide ini? Orang yang akan relevan dalam tinjauan sejawat tetapi tidak akan berubah menjadi kegiatan daftar periksa tanpa berpikir yang menghasilkan catatan tidak lebih membantu daripada: "Anda lupa mengomentari saluran 42".

Ini jelas berjalan di atas dan di luar dokumentasi - ini menyentuh bagaimana kode terstruktur, algoritma mana yang dipilih, dll. Bahkan mungkin menyentuh analisis persyaratan dan desain.

Aturan # 1 saya adalah "Jangan mendokumentasikan yang sudah jelas." Aturan # 2 adalah "Tulis kode yang jelas".

Untuk kode kritis-keselamatan (yang belum pernah saya kerjakan, terima kasih Tuhan), ini perlu tapi tidak ada langkah awal yang cukup dekat. Bahkan mungkin harus turun ke mandat fitur bahasa apa yang harus dihindari (saya telah melihat lebih dari satu standar mandat "Anda tidak boleh menggunakan scanf( "%s", input ); untuk alasan apa pun ").

Praktik terbaik kode yang mendokumentasikan diri sendiri bukan merupakan konsensus umum - walaupun dapat diterima secara luas bahwa kode yang mudah dipahami lebih baik daripada kode kriptik, tidak semua orang setuju apakah kode rumit harus selalu direaktor ulang atau tidak jika berkomentar saya t.

Tapi debat ini adalah tentang potongan - potongan kode yang sulit dipahami - dan Anda berbicara tentang mengomentari setiap baris kode. Baris-baris kode yang sulit dipahami seharusnya sangat jarang - jika sebagian besar baris Anda rumit seperti ini daripada Anda menggunakan smart-ass one-liners secara berlebihan dan Anda harus berhenti! Tentu saja, peran baris terkadang agak sulit untuk dipahami, tetapi itulah perannya dalam konteks sepotong kode yang lebih besar - apa yang dilakukan baris itu sendiri hampir selalu mudah.

Jadi, Anda seharusnya tidak mengomentari baris - Anda harus mengomentari potongan kode. Komentar spesifik dapat ditempatkan di dekat garis yang mereka rujuk, tetapi komentar ini masih mengacu pada kode yang lebih besar. Mereka tidak menjelaskan apa / mengapa baris itu - mereka menggambarkan apa yang dilakukannya dalam kode itu dan / atau mengapa diperlukan dalam kode itu.

Jadi, bukan baris yang harus dikomentari tetapi potongan kode yang lebih besar. Haruskah setiap bagian kode dikomentari? Tidak. Harold Abelson mengatakan bahwa " Program harus ditulis untuk dibaca orang, dan hanya untuk mesin yang dieksekusi ". Tetapi komentar hanya untuk dibaca orang - mesin tidak menjalankannya. Jika standar pengkodean Anda memaksa menulis komentar yang berlebihan pada setiap baris / kode Anda tidak hanya membebani pengembang yang perlu menulisnya - Anda juga membebani pengembang yang harus membacanya !

Ini adalah masalah, karena ketika sebagian besar komentar yang Anda baca berlebihan, Anda berhenti memperhatikannya (karena Anda tahu mereka hanya akan menjadi sampah yang berlebihan), dan kemudian Anda akan kehilangan komentar penting . Jadi saya katakan - hanya tulis komentar penting, sehingga ketika seseorang melihat komentar dalam kode mereka akan tahu ada baiknya membacanya untuk memahami kode.

IMHO itu harus melakukan keduanya. Mengomentari setiap kalimat konyol, karena Anda berakhir dengan kalimat seperti

  i++;    /* Increment i */

sama sekali tidak tahu mengapa Anda ingin meningkatkan i. Perluas sedikit itu, dan Anda memiliki gaya khas komentar Doxygen, yang menghasilkan sejumlah besar kata-kata tanpa memberikan ide apa pun untuk kode tersebut, atau cara kerjanya. (Setidaknya sejauh yang pernah saya lihat: Saya mengakui bahwa mungkin saja menulis dokumentasi yang bermanfaat menggunakan sistem seperti itu, tetapi saya tidak menahan nafas.)

OTOH, jika Anda menulis blok komentar yang baik di bagian atas fungsi (atau pengelompokan apa pun yang logis), yang menggambarkan apa yang harus dicapai, dan bagaimana, jika kurang jelas, Anda memiliki sesuatu yang berguna. Jika Anda adalah saya, Anda mungkin bahkan memasukkan kode LaTeX untuk persamaan yang relevan, atau referensi ke makalah, misalnya "Ini mengimplementasikan skema WENO untuk menyelesaikan persamaan Hamilton-Jacobi, seperti yang dibahas dalam ..."

Saatnya mengembalikan diagram alur! (tidak benar-benar tetapi tunggu sebentar)

Suatu hari saya menemukan template flowchart lama saya. Saya hanya menggunakannya untuk pekerjaan rumah dan lelucon (Anda harus menyukai diagram alur yang baik). Tetapi bahkan pada saat ini sebagian besar programmer komersial yang masih menggunakan diagram alir menghasilkannya secara otomatis dari kode (yang benar-benar merusak tujuan asli diagram alur, yang akan menjadi pembantu dalam penulisan kode yang lebih baik dan cukup berguna dalam kode mesin. Namun dengan bahasa tingkat yang lebih tinggi, diagram alir berubah dari menjadi kruk menjadi hobi. Mengapa abstraksi dari diagram alur itu sama dengan kode. Komentar yang baik berada pada tingkat abstraksi yang berbeda dari kode. Cara termudah untuk melakukan ini adalah dengan menggunakan komentar untuk alasan sementara kode menangani apa.

Saya akan menjawab pertanyaan seperti yang dinyatakan:

Mengingat semua ini, apakah mungkin untuk menulis standar pengkodean yang baik yang menangkap ide ini?

Iya. WYSIWYG. Standar pengkodean yang baik secara harfiah " jelas bagi pembaca apa yang dilakukan kode berikut dan mengapa ".

Dengan kata lain, komentar ulasan kode saya tentang keterbacaan kode secara harfiah, 1-1, muncul dari kondisi mental saya

Saya, sebagai pembaca, (lebih baik lagi, sebagai standar minimal, model mental pembaca yang kurang berpengalaman tetapi masuk akal), tidak akan mengerti tujuan kode berikut, atau metode kerja

Secara umum, orang mudah masuk "ini membutuhkan lebih banyak keterbacaan" ketika mereka mendengar "Saya, sebagai pengembang senior yang semoga Anda hormati tidak bodoh, pada awalnya tidak membaca memahami kode ini atau mengapa ada atau apa itu tidak, jadi perlu dijelaskan ".

Ini menggeser wacana dari "Anda tidak mengikuti standar yang tidak berarti" ke "kode Anda memiliki kekurangan keterbacaan khusus yang mengarah ke masalah praktis ".

Standar kedua yang perlu dibuat eksplisit adalah "tes darurat 02:00".

Bisakah cadangan Anda, yang tidak berpengalaman dengan kode ini, mencari tahu apa masalahnya dengan kode ketika debugging selama panggilan darurat produksi 02:00, ketika Anda sedang berlibur di Andes Chili tanpa ponsel?

Ini mungkin terdengar subyektif tetapi sebenarnya mudah diukur secara praktis: memanggil anggota tim junior acak yang diharapkan menjadi debugging pada malam hari dalam keadaan darurat produksi, dan meminta mereka untuk menjelaskan bagaimana kode khusus yang tidak dikomentari bekerja dan mengapa sana.

Jawaban ini mencakup sebagian besar masalah, namun ada satu hal penting.

Saya ingin menangkap ide di sepanjang baris: pertimbangkan komentar untuk setiap baris, urutan, pernyataan, bagian, struktur, fungsi, metode, kelas, paket, komponen, ... kode.

Ada alat untuk menghasilkan dokumentasi dari kode, seperti misalnya oksigen. Jika Anda menggunakan alat seperti itu, maka masuk akal untuk berkomentar file, fungsi, kelas, dll. Bahkan jika nama fungsi cukup jelas, saya masih melakukannya untuk konsistensi, karena orang yang membaca dokumentasi akan berterima kasih.

Banyak jawaban yang ada terinci dengan baik, tetapi saya merasa penting untuk menjawab:

... [komentar] yang akan relevan dalam tinjauan sejawat tetapi tidak akan berubah menjadi kegiatan daftar periksa tanpa pertimbangan ...

Bagi saya satu-satunya komentar yang bisa menjadi standar dapat dijawab dengan menanyakan komentar apa yang diperhatikan ketika tidak ada . Dengan kata lain: komentar yang digunakan oleh IDE atau perangkat lunak dokumentasi.

Yang sedang berkata, ini subjektif untuk alat apa yang digunakan oleh pengembang, dan tidak semua komentar yang digunakan oleh perangkat lunak tersebut sama bermanfaatnya satu sama lain .