Apa pendapat Anda tentang Periode / Berhenti Penuh dalam komentar kode? [Tutup]

Saya melihat ini ditanyakan di SO Tavern , jadi saya memposting pertanyaan di sini. Saya pikir itu pertanyaan yang menarik. (Tentu saja itu bukan milik SO, tapi saya pikir tidak masalah di sini.)

Apakah Anda menambahkan titik (atau, seperti OP menulis, "berhenti penuh") dalam komentar kode Anda?

Agar tetap relevan, mengapa ?

Pemberhentian penuh adalah untuk mengakhiri kalimat, tetapi jika komentar hanya terdiri dari satu kalimat yang dikelilingi oleh kode, maka penghentian penuh tidak diperlukan menurut saya. Kadang-kadang saya bahkan tidak menggunakan huruf besar untuk huruf pertama. Komentar multiline yang terperinci, di sisi lain, memang membutuhkan tanda baca lengkap.

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}

Ya, Karena komentar dalam bahasa Inggris, dan bahasa Inggris yang tepat menggunakan tanda baca.

Apakah Anda menambahkan titik (atau, seperti OP menulis, "berhenti penuh") dalam komentar kode Anda?

Agar tetap relevan, mengapa?

Untuk alasan yang sama saya menambahkan mereka ketika menulis teks "normal" - mereka adalah bagian dari bahasa secara tertulis, dan seharusnya tidak ada sesuatu yang istimewa tentang mereka. Saya menggunakannya dengan sama ketika menulis satu kalimat (satu baris) komentar serta seluruh paragraf.

Kode sumber bukan teks biasa, dan oleh karena itu kami menggunakan aturan berbeda untuknya. Sederhana ;-)

Jika Anda menulis komentar orang akan berharap itu ditulis dalam bahasa Inggris. Karena itu, seseorang harus memberi tanda baca dengan benar. Melakukan yang sebaliknya akan menjadi malas.

Jika saya menulis kalimat lengkap (atau lebih), maka ya. Jika tidak, maka kadang tidak, tetapi biasanya tetap ya.

Saya juga terkadang menjadi gila dan menggunakan tanda seru, tanda tanya, dll;)

Adapun mengapa, itu sebagian karena saya hanya khusus seperti itu dan sebagian karena saya menemukan bahwa tanda baca yang tepat dapat menambah banyak kejelasan.

Jawaban lain dan popularitas mereka telah memperjelas bahwa perhentian penuh sangat dihargai dalam komentar yang lebih panjang, dan mungkin dapat dihindari dalam satu kalimat.

Poin lain yang mungkin relevan adalah untuk menghindari tanda seru, terutama kelipatan . Contoh:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

dan

    // This code really sucks!

Di sisi lain, tanda tanya terkadang sangat berguna:

    // TODO: What does Crojpler.bway() actually do?

Tergantung. Jika saya menulis paragraf besar dan tepat yang menjelaskan apa yang dilakukan oleh satu blok kode, maka saya memberi tanda baca dengan benar, seperti tulisan lain yang tepat. OTOH, ketika saya hanya berkomentar satu baris kode, maka saya tidak.

Mengapa? - Mirip dengan mengapa saya menulis email menggunakan penulisan yang tepat, sementara saya mungkin menggunakan kalimat steno dalam pesan SMS. Dalam satu kasus saya sedang duduk untuk menulis blok teks yang tepat, jadi saya hanya secara otomatis "melakukannya dengan benar", sementara di yang lain itu hanya catatan singkat untuk mendapatkan poin.

Contoh nyata dari kode saya:

Komentar catatan cepat:

// check for vk_enter

Dokumentasi metode "Tepat":

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.

Ya saya pikir dengan cara ini Anda membuat konvensi pengkodean yang baik dan juga membuat kode yang mudah dibaca untuk orang ketiga yang meninjau kode Anda.

Saya akan selalu menggunakan huruf besar dan tanda baca dengan benar saat membuat komentar XML yang saya harapkan dapat dilihat di IntelliSense dan dalam dokumentasi yang kami buat . Ini adalah konstruksi yang jauh lebih formal dan harus diperlakukan seperti itu.

Komentar yang baru saja dilihat di badan blok kode, harusnya sejelas mungkin. Terserah programmer bagaimana mereka mencapainya.