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 tables
dan chairs
bisa 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 = 0
SETELAH 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.