Apakah "komentar lucu" adalah praktik yang buruk atau tidak? [Tutup]

Saya ingin bertanya kepada Anda apakah menambahkan beberapa "telur paskah" dalam dokumentasi sumber tidak profesional atau tidak. Mungkin Anda memiliki membaca StackOverflow jajak pendapat untuk komentar lucu dalam sumber dokumentasi, dan saya secara pribadi telah tersandung di banyak hal-hal seperti selama saya bekerja, termasuk lucu (atau tidak) hal-hal dalam dokumentasi API publik (misalnya lemah ini BZZZTT !! 1! Hal dalam dokumentasi publik Android, saya dapat memberikan setidaknya selusin contoh lagi).

Saya tidak bisa sampai pada pendapat akhir untuk diri saya sendiri, karena saya sendiri memiliki argumen yang bertentangan.

Argumen pro:

• Itu bisa menghibur seseorang, dan membuat harinya lebih lucu / lebih produktif. Sebagian besar kode sumber tidak perlu dikomentari pula (jika proyek dilakukan dengan benar), karena metode spesifik (misalnya) cukup jelas, atau jika itu adalah tumpukan kode jelek yang aneh, ia tidak bisa dijelaskan dengan cara yang bermakna, sehingga lelucon lucu tidak membahayakan info yang mungkin bisa Anda peroleh dari dokter.

Argumen kontra:

• Jika Anda sangat terkonsentrasi / frustrasi, hal terakhir yang Anda butuhkan adalah lelucon bodoh seseorang, alih-alih memberi Anda informasi yang Anda butuhkan tentang bagian kode yang terdokumentasi, itu hanya dapat membuat Anda semakin frustrasi. Dan gagasan tentang bagaimana dokumentasi akan terlihat jika semua orang mulai melakukannya adalah mengerikan. Ditambah lagi lelaki yang menulis lelucon mungkin satu-satunya yang berpikir bahwa itu lucu / menarik / layak buang waktu untuk membacanya.

Apa yang kamu pikirkan?

Saya pikir komentar lucu itu membuang waktu - buang waktu untuk menulis, buang waktu untuk membaca, buang waktu untuk menunjukkan kepada rekan kerja Anda komentar lucu yang (hampir selalu) hanya membingungkan dan sebagainya.

Tapi ... tidak ada yang benar-benar bekerja pada 100% sepanjang hari setiap hari (situs-situs seperti ini akan kosong jika kita lakukan) dan humor asli memecah hari dan membantu menjaga moral.

Saya masih akan menentangnya hanya karena setiap komentar 'lucu' yang pernah saya baca mungkin lucu pada saat itu - tetapi saya belum melihat satu yang benar-benar lucu, sebagian besar hanya membingungkan atau jauh di dalam hati. -lelucon.

Jika komentar lucu benar-benar lucu, itu akan mengubah pikiran saya. Tetapi begitu Anda mendorong lelucon, apakah Anda mendorong sumpah atau penghinaan atau kejahatan?

Saya penggemar komentar lucu .

Anda harus selalu profesional dalam berkomentar, tetapi humor tidak akan membunuh pembaca.

Terutama jika pembaca adalah anggota tim Anda.

Yang paling tidak saya sukai, adalah pengembang yang menganggap diri mereka terlalu serius. Saya pikir kita harus bersenang-senang di tempat kerja, atau bekerja tidak sepadan.

Jika ada artinya, tidak apa-apa untuk menjadi lucu. Menjelaskan sesuatu dalam komentar dengan cara yang lucu tidak masalah. Namun, jika itu hanya sesuatu yang lucu dan tidak mengandung nilai aktual sebagai komentar, itu hanya mengganggu. Selalu ingat bahwa alasan untuk komentar adalah untuk membuat perawatan lebih efisien. Humor tidak harus bertentangan dengan itu, tetapi bisa jika tidak dilakukan dengan tepat.

Kode dimaksudkan untuk membaca ... berkali-kali.

Berapa banyak lelucon yang Anda tahu lucu setelah menceritakan yang keseratus?

Komentar lucu itu bagus.

• Ini memberikan getaran positif ke kode Anda yang tampaknya membosankan.
• Jika Anda mendapatkan waktu Anda dengan benar. Itu menjelaskan jauh lebih baik daripada komentar membosankan biasa. Yang saya maksud dengan 'timing' di sini adalah relevansi dengan kode di bawah komentar.
• Kode Anda akan diingat oleh banyak orang, karena emosi diberikan tempat yang lebih baik dalam ingatan (manusia). Ini adalah trik hebat jika Anda ingin lebih banyak orang bekerja dengan Anda pada proyek open-source.
• Umumnya membantu dalam ulasan. Itu membuat kode Anda jauh lebih tertahankan. Tentu saja Anda harus terlebih dahulu berkonsentrasi pada penulisan kode yang baik. Saya merasa ketika seseorang percaya diri dengan kode yang mereka tulis, komentar lucu hanyalah efek samping.

Hanya saja, jangan lucu seperti orang ini ;)

Inilah yang saya tulis jam dua pagi ("DQ" adalah inisial perusahaan saya):

// Twas the night before go-live and all through DQ
// the devs were all crying and yes, this means you.
// Keys had been saved with both hyphens and 'scores
// which left this programmer with finger pad sores.
// The solution I crafted, you'll likely find lacking:
// to OR them together with judicuous hacking.

$hyphenated = str_replace('_','-',$data_type_key);
$underscored = str_replace('-','_',$data_type_key);
// (and then see line 46)

Jika Anda meninjau kode sumber Anda di depan pelanggan, apakah Anda akan malu?

Tampaknya tidak ada jawaban saat ini yang memperhitungkannya. Beberapa pelanggan tidak memiliki selera humor dan akan menganggap lelucon itu sebagai indikator bahwa Anda tidak menganggap serius pekerjaan Anda. Mereka akan menyimpulkan bahwa Anda ceroboh dengan pekerjaan Anda.

Komentar kode lucu terkadang tidak profesional dan tidak pantas.

Di luar apa yang sudah dikatakan, jika Anda bekerja di tim internasional, beberapa rekan di luar negeri Anda mungkin tidak mendapatkan lelucon, karena beberapa referensi budaya lokal atau permainan kata-kata yang tidak dipahami oleh seseorang yang bahasa Inggrisnya bukan bahasa asli . Hal yang sama berlaku untuk proyek sumber terbuka.

Jika efisien dan tidak membuang waktu pembaca (baik membaca / memahami) maka saya tidak melihat masalah dengan sedikit humor.

Sama seperti lelucon di dunia nyata, jika Anda membuatnya sepanjang waktu itu tidak lucu, tidak produktif, dan tidak profesional. Tapi ada waktu dan tempat untuk semua lelucon, dan ada waktu dan tempat dalam kode. Sama seperti di dunia nyata, ia tahu di mana, kapan, dan bagaimana membuat lelucon.

Tergantung, untuk tugas di perguruan tinggi, saya hampir selalu melakukan komentar lucu, karena saya tahu itu tidak akan pernah digunakan dan hanya tugas pekerjaan rumah.

Untuk proyek-proyek yang lebih serius, saya masih menggunakannya di sana-sini, tetapi tidak lazim, sehingga menyebalkan atau sulit dipahami, menentang tujuan komentar.

Saya ingat melakukan sedikit pemrograman web, di mana saya harus menghindari ketidakcocokan browser dan gangguan aneh. Terkadang diakhiri dengan komentar penuh kemarahan dan kebencian pada.js file.

Aturan dasar saya adalah: Jika agak jelas apa yang dilakukan bagian kode, KOMENTAR LUCU MENGHIDUPKAN!

Jika kodenya begitu kabur dan membingungkan (seperti " kelas inline "), saya lebih baik menggunakan komentar saya akan mengerti diri sendiri dalam beberapa hari ...