Saya ingin mendengar dari Anda saran dan pengalaman menulis komentar dalam kode Anda. Bagaimana Anda menulisnya dengan cara yang paling mudah dan informatif? Kebiasaan apa yang Anda miliki ketika mengomentari bagian kode? Mungkin beberapa rekomendasi eksotis?

Saya harap pertanyaan ini akan mengumpulkan saran dan rekomendasi paling menarik untuk datang, sesuatu yang berguna yang dapat dipelajari semua orang.

Oke, saya akan mulai.

1. Biasanya, saya tidak menggunakan /* */komentar bahkan ketika saya perlu mengomentari banyak baris.

   Keuntungan : kode secara visual terlihat lebih baik daripada ketika Anda mencampur sintaks seperti itu dengan komentar satu baris. Sebagian besar IDE memiliki kemampuan untuk mengomentari teks yang dipilih dan mereka biasanya melakukannya dengan sintaksis satu baris.

   Kekurangan : Sulit untuk mengedit kode seperti itu tanpa IDE.

2. Tempatkan "titik" di akhir setiap komentar selesai.

   Sebagai contoh:

   //Recognize wallpaper style. Here I wanted to add additional details
   int style = int.Parse(styleValue);
   //Apply style to image.
   Apply(style);
   

   Keuntungan : Tempatkan "titik" hanya di komentar yang Anda selesai. Terkadang Anda dapat menulis informasi sementara, jadi kekurangan "dot" akan memberi tahu Anda bahwa Anda ingin kembali dan menambahkan beberapa teks tambahan ke komentar ini.

3. Sejajarkan teks dalam enumerasi, parameter komentar, dll.

   Sebagai contoh:

   public enum WallpaperStyle
   {
       Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
       SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
       Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
       Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
       Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
   };
   

   Keuntungan : Hanya terlihat lebih baik dan secara visual lebih mudah untuk menemukan apa yang Anda butuhkan.

   Kekurangan : Menghabiskan waktu untuk menyelaraskan dan lebih sulit untuk mengedit.

4. Tulis teks dalam komentar yang tidak dapat Anda peroleh dengan menganalisis kode.

   Misalnya, komentar bodoh:

   //Apply style.
   Apply(style);
   

   Keuntungan : Anda akan memiliki kode yang jelas dan kecil dengan hanya informasi yang berguna di komentar.

Beberapa pernyataan di bawah ini cukup pribadi, meskipun dengan beberapa pembenaran, dan dimaksudkan seperti ini.

Jenis Komentar

Untuk versi singkat ... Saya menggunakan komentar untuk:

• mengekor komentar yang menjelaskan bidang dalam struktur data (selain dari itu, saya tidak benar-benar menggunakan komentar satu baris)
• komentar multi-garis yang luar biasa atau berorientasi tujuan di atas blok
• pengguna publik dan / atau dokumentasi pengembang dihasilkan dari sumber

Baca di bawah untuk detailnya dan (mungkin tidak jelas) alasannya.

Komentar Terakhir

Bergantung pada bahasanya, baik menggunakan komentar baris tunggal atau komentar multi baris Mengapa itu tergantung? Itu hanya masalah standardisasi. Ketika saya menulis kode C, saya menyukai kode ANSI C89 kuno secara default, jadi saya lebih suka selalu memilikinya /* comments */.

Oleh karena itu saya akan memiliki ini di C sebagian besar waktu, dan kadang-kadang (tergantung pada gaya basis kode) untuk bahasa dengan sintaks mirip C:

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs baik dan melakukan itu untukku M-;.

Jika bahasa mendukung komentar baris tunggal dan bukan berbasis C, saya akan lebih cenderung menggunakan komentar baris tunggal. Kalau tidak, aku takut sekarang aku sudah terbiasa. Yang tidak selalu buruk, karena memaksa saya untuk ringkas.

Komentar Multi-Baris

Saya tidak setuju dengan ajaran Anda menggunakan komentar single-line karena ini lebih menarik secara visual. Saya menggunakan ini:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

Atau ini (tapi saya tidak sering melakukannya lagi, kecuali pada basis kode pribadi atau kebanyakan untuk pemberitahuan hak cipta - ini adalah sejarah bagi saya dan berasal dari latar belakang pendidikan saya. Sayangnya, sebagian besar IDE mengacaukannya ketika menggunakan format otomatis) :

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

Jika perlu, maka saya akan berkomentar inline menggunakan apa yang saya sebutkan sebelumnya untuk komentar tertinggal, jika masuk akal untuk menggunakannya dalam posisi trailing. Pada kasus pengembalian yang sangat khusus, misalnya, atau untuk dokumen switch's casepernyataan (jarang, saya tidak menggunakan beralih sering), atau ketika saya mendokumentasikan cabang di if ... elsealiran kontrol. Jika itu bukan salah satunya, biasanya blok komentar di luar ruang lingkup yang menguraikan langkah-langkah fungsi / metode / blok lebih masuk akal bagi saya.

Saya menggunakan ini sangat luar biasa, kecuali jika pengkodean dalam bahasa tanpa dukungan untuk komentar dokumentasi (lihat di bawah); dalam hal ini mereka menjadi lebih umum. Tetapi dalam kasus umum, itu hanya untuk mendokumentasikan hal-hal yang dimaksudkan untuk pengembang lain dan merupakan komentar internal yang benar-benar harus benar-benar menonjol. Misalnya, untuk mendokumentasikan blok kosong wajib seperti blok "terpaksa" catch:

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

Yang sudah jelek bagi saya tetapi saya akan mentolerir dalam beberapa keadaan.

Komentar Dokumentasi

Javadoc & al.

Saya biasanya menggunakannya pada metode dan kelas untuk mendokumentasikan versi memperkenalkan fitur (atau mengubahnya) terutama jika itu untuk API publik, dan untuk memberikan beberapa contoh (dengan kasus input dan output yang jelas, dan kasus khusus). Meskipun dalam beberapa kasus kasus unit mungkin lebih baik untuk mendokumentasikan ini, tes unit tidak selalu dapat dibaca manusia (tidak peduli apa pun DSL yang Anda gunakan).

Mereka sedikit mengganggu saya untuk mendokumentasikan bidang / properti, karena saya lebih suka mengekor komentar untuk ini dan tidak semua kerangka kerja generasi dokumentasi mendukung komentar dokumentasi. Doxygen memang, misalnya, tetapi JavaDoc tidak, yang berarti Anda memerlukan komentar teratas untuk semua bidang Anda. Saya dapat bertahan meskipun demikian, karena garis Jawa relatif panjang di sebagian besar waktu, jadi komentar tambahan akan menyeret saya keluar secara merata dengan memperluas garis di luar batas toleransi saya. Jika Javadoc akan mempertimbangkan untuk meningkatkan itu, saya akan jauh lebih bahagia.

Kode Komentar-Keluar

Saya menggunakan single-line hanya untuk satu alasan, dalam bahasa seperti C (kecuali jika mengkompilasi untuk ketat C, di mana saya benar-benar tidak menggunakannya): untuk mengomentari hal-hal saat pengkodean. Sebagian besar IDE harus beralih untuk komentar baris tunggal (selaras pada indentasi, atau pada kolom 0), dan itu cocok dengan use case untuk saya. Menggunakan toggle untuk komentar multi-baris (atau memilih di tengah-tengah baris, untuk beberapa IDE) akan membuatnya lebih sulit untuk beralih di antara komentar / tanda komentar dengan mudah.

Tapi karena saya menentang kode commented-out di SCM, itu biasanya sangat singkat karena saya akan menghapus potongan-potongan commented sebelum melakukan. (Baca jawaban saya untuk pertanyaan ini pada "komentar in-line dan SCM yang diedit oleh ) "

Gaya Komentar

Saya biasanya cenderung menulis:

• lengkapi kalimat dengan tata bahasa yang benar (termasuk tanda baca) untuk komentar dokumentasi, karena seharusnya dibaca nanti dalam dokumen API atau bahkan sebagai bagian dari manual yang dihasilkan.
• diformat dengan baik tetapi lebih longgar pada tanda baca / huruf besar untuk blok komentar multi-baris
• membuntuti blok tanpa tanda baca (karena ruang dan biasanya karena komentarnya singkat, yang lebih mirip pernyataan yang ditulis dalam tanda kurung)

Catatan tentang Pemrograman Literate

Anda mungkin ingin tertarik pada Pemrograman Sastra , seperti yang diperkenalkan dalam makalah ini oleh Donald Knuth .

Paradigma pemrograman melek huruf, [...] merepresentasikan perpindahan dari penulisan program dengan cara dan ketertiban yang diberlakukan oleh komputer, dan sebagai gantinya memungkinkan programmer untuk mengembangkan program dalam urutan yang dituntut oleh logika dan aliran pemikiran mereka. 2 Program melek ditulis sebagai eksposisi logika yang tidak terputus dalam bahasa manusia biasa, seperti teks esai [...].

Alat pemrograman melek digunakan untuk mendapatkan dua representasi dari file sumber melek: satu cocok untuk kompilasi lebih lanjut atau eksekusi oleh komputer, kode "kusut", dan satu lagi untuk dilihat sebagai dokumentasi yang diformat, yang dikatakan "ditenun" dari sumber melek.

Sebagai catatan dan contoh: Kerangka JavaScript underscore.js , meskipun ketidakpatuhan dengan gaya komentar saya, adalah contoh yang cukup bagus dari basis kode dokumen yang baik dan sumber beranotasi yang terbentuk dengan baik - meskipun mungkin bukan yang terbaik untuk digunakan sebagai referensi API).

Ini adalah konvensi pribadi . Ya, saya mungkin aneh (dan Anda mungkin juga). Tidak apa-apa, selama Anda mengikuti dan mematuhi konvensi kode tim Anda ketika bekerja dengan teman sebaya, atau tidak secara radikal menyerang preferensi mereka dan hidup bersama dengan baik. Ini adalah bagian dari gaya Anda, dan Anda harus menemukan garis tipis antara mengembangkan gaya pengkodean yang mendefinisikan Anda sebagai pembuat kode (atau sebagai pengikut aliran pemikiran atau organisasi yang Anda hubungkan) dan menghormati konvensi kelompok untuk konsistensi. .

Ketika saya pergi ke universitas saya selalu diajarkan untuk berkomentar setiap baris kode dan setiap header metode. Itu drum di / diindoktrinasi sedemikian rupa sehingga Anda melakukannya tanpa pertanyaan. Setelah menjadi bagian dari beberapa tim pengembangan Agile di perusahaan yang berbeda saya dapat mengatakan bahwa saya dapat menulis komentar sekali dalam bulan biru.

Alasannya ada dua, pertama-tama kita tidak boleh lagi menulis metode monolitik panjang yang melakukan 101 hal yang berbeda, kelas, metode dan nama variabel harus mendokumentasikan diri. Ambil metode login berikut sebagai contoh.

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

Ini dapat ditulis ulang untuk sesuatu yang jauh lebih mudah dibaca dan mungkin dapat digunakan kembali:

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

Anda dapat melihat dengan jelas dari metode login apa yang sedang terjadi. Anda mungkin melihat ini sebagai pekerjaan tambahan tetapi metode Anda kecil dan hanya memiliki satu pekerjaan. Selain itu, nama metode bersifat deskriptif sehingga tidak perlu menulis komentar tajuk metode apa pun. Jika Anda berakhir dengan terlalu banyak metode ini merupakan indikasi bahwa metode terkait harus difaktorkan ulang ke objek lain seperti UserAuthenticationService, ingat objek hanya boleh memiliki satu pekerjaan.

Kedua, setiap bagian kode yang Anda tulis, termasuk komentar, harus dipertahankan, semakin banyak komentar yang Anda miliki, semakin banyak yang harus dipelihara. Jika Anda mengubah nama kelas atau variabel Anda akan mendapatkan kesalahan kompilasi tetapi jika Anda mengubah cara bagian kode bekerja atau menghapusnya dan tidak memperbarui komentar terkait maka tidak akan ada kesalahan kompilasi dan komentar akan berkeliaran menyebabkan kebingungan .

Jika Anda menulis API maka saya yakin bahwa setiap antarmuka publik, kelas, enumerasi harus memiliki komentar header yang ditulis dengan baik untuk dokumentasi.

Kurang fokus pada format dan lebih banyak pada konten. Misalnya komentar dalam contoh Anda memberi tahu saya tidak ada yang baru. Mereka lebih buruk daripada tidak berharga karena mereka mengurangi membaca kode, dan komentar seperti ini paling tidak merupakan referensi yang samar-samar tentang apa yang dipikirkan oleh programmer asli yang dia lakukan pada saat dia menulisnya. Saya dapat melihat dari contoh kode bahwa Anda menerapkan gaya "apply (Style)", saya dapat membaca sumber. Saya tidak dapat membaca pikiran Anda, - mengapa Anda melakukannya adalah apa yang harus disampaikan oleh komentar itu kepada saya. misal daripada

//Apply style.

Apply(style);

seharusnya

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

Sebagian besar dari kita bekerja dalam tim pada kode yang ada, memformat cara anggota tim lainnya, cara itu sudah dilakukan. Konsistensi jauh lebih penting daripada cantik.

Sebisa mungkin, tulis kode Anda sehingga komentar akan sepenuhnya asing. Hanya tambahkan komentar ketika kode tidak dapat ditulis sedemikian rupa sehingga akan membuat konsep penting menjadi jelas.

Preferensi saya sendiri adalah menjaganya tetap sederhana. Saya menghindari semua jenis format mewah. Alasan utama untuk ini adalah saya pikir kode sumber harus dapat diedit dengan nyaman bahkan dengan editor teks yang paling sederhana. Saya juga tidak pernah susah membungkus paragraf teks melainkan membiarkan editor melakukan soft wrapping (tidak ada penambahan baris baru).

Saya sering melihat komentar seperti itu, dan beberapa alat secara otomatis menghasilkan seperti itu:

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

Kurang dua baris:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

IDE dan Editor, sedikit di atas tingkat notepad, dapat mendeteksi komentar dan mencetaknya dalam warna yang berbeda. Tidak perlu menghiasi awal garis dengan asterix.

Anda bahkan menyimpan beberapa byte, jika Anda menggunakan tab untuk indentasi.

Jika Anda tidak menggunakan editor canggih, yang membuat komentar dengan nada abu-abu, sejumlah besar asterix akan berfungsi sebagai penekanan dan menarik perhatian Anda, yang merupakan kebalikan dari hal yang benar untuk dilakukan: untuk tetap tinggal.

Inilah "anti-pola" yang saya temukan di seluruh kode pekerjaan saya: Penggunaan komentar sebagai "log perubahan"; itulah gunanya log dalam sistem kontrol versi Anda. Kode penuh dengan hal-hal seperti:

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

dan biasanya sering menyertakan kode lama yang telah dikomentari (sekali lagi, itulah inti dari sistem VCS sehingga tidak perlu berada dalam kode setelah kode baru ditulis). Juga sesuatu yang harus dihindari adalah komentar berulang seperti "Mengapa kita membutuhkan ini?" atau lebih buruk lagi, "Ini mungkin harus diganti namanya" (karena ada alat canggih untuk mengubah nama, jadi pada saat Anda perlu menulis komentar itu Anda bisa mengganti namanya). Sekali lagi, saya berurusan dengan kedua komentar itu secara teratur, di sepanjang baris:

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

1. Pilih sistem dokumentasi seperti doxygen dan tetap menggunakannya. Terus periksa dokumen yang dihasilkan.
2. Coba gambarkan seseorang yang baru ke basis kode masuk dan membaca dokumen Anda, bisakah mereka mulai menjalankannya? Peserta magang sebenarnya baik untuk itu, duduklah yang baru dengan basis dokumen yang ada dan tugas sederhana dan lihat seberapa jauh mereka, jika mereka tersandung, sangat yakin apa pun yang Anda katakan agar mereka lakukan lagi masuk dalam dokumen.
3. Buat komentar dokumentasi sebagai pos pemeriksaan dalam proses peninjauan Anda.

Pembaca kode biasanya mencoba menjawab tiga pertanyaan:

1. Apa yang dilakukan kelas atau fungsi ini? Jika ini sulit dijawab, maka itu terlalu banyak. Kode yang sulit didokumentasikan biasanya hanya salah.
2. Bagaimana saya menggunakannya? Contoh mungkin cukup bagus.
3. Kode itu mengejutkan. Kenapa kau melakukan itu? Jawaban yang paling mungkin: untuk mengatasi bug dalam komponen pihak ketiga, karena teknik yang jelas terbukti terlalu lambat

Segala sesuatu yang lain harus dinyatakan dalam kode. Seperti menulis prosa, ini adalah seni, dan membutuhkan banyak latihan. Satu-satunya cara untuk mengetahui apakah kode Anda dapat dimengerti adalah membuat orang lain membacanya. Ketika mereka tidak memahami sesuatu, jangan jelaskan secara lisan. Perbaiki kodenya. Tambahkan komentar sebagai pilihan terakhir.

Jika saya melihat "panjang ganda" saya akan bertanya "Apa satuan pengukuran?" Jangan menambahkan komentar. Ubah nama variabel. Jika saya melihat blok kode dan saya berkata "apa fungsinya?", Jangan menambahkan komentar. Ekstrak fungsi dengan nama yang bermakna. Jika Anda tidak dapat mengekstrak fungsi karena membutuhkan 17 argumen, maka perbaiki kode tersebut.