Setiap kali saya menulis if-else-construct dalam bahasa apa pun, saya bertanya-tanya apa yang akan menjadi cara terbaik (dalam hal keterbacaan dan tinjauan) untuk menambahkan komentar. Terutama ketika mengomentari klausa lain, komentar selalu terasa tidak pada tempatnya bagi saya. Katakanlah kita memiliki konstruk seperti ini (contoh ditulis dalam PHP):

if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

Saya bisa berkomentar seperti ini:

// check, what kind of magic should happen
if ($big == true) {
    // do some big magic stuff
    bigMagic();
} else {
    // small magic is enough
    smallMagic()
}

atau

// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
    bigMagic();
}
// small magic is enough
else {
   smallMagic()
}

atau

// check, what kind of magic should happen
// if:   do some big magic stuff
// else: small magic is enough
if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

Apa contoh praktik terbaik Anda untuk mengomentari ini?

Saya lebih suka:

if ($magic == big) {
    bigMagic();
}
else {
    smallMagic();
}

atau:

if ($magic == big) {
    // big magic requires a big surprise, so I'm telling you about it here
    surprisingThing();
}
else {
    // give a magical feeling even if $magic is noMagicAtAll
    smallMagic();
}

Agak konyol untuk menulis komentar yang menjelaskan apa yang diperiksa kondisi Anda kecuali jika kode tidak menyatakannya dengan jelas. Meski begitu, lebih baik menulis ulang kode untuk membuatnya sejelas mungkin. Hal yang sama berlaku untuk badan-badan blok bersyarat - jika Anda dapat membuat alasan untuk melakukan sesuatu yang jelas, lakukan itu alih-alih berkomentar.

Saya tidak berlangganan filosofi "tidak pernah menulis komentar", tetapi saya percaya menghindari komentar yang mengatakan apa yang seharusnya dikatakan oleh kode. Jika Anda menulis komentar seperti "periksa keajaiban apa yang harus terjadi" ketika kode itu bisa mengatakan if ($magic == big) {..., pembaca akan berhenti membaca komentar Anda dengan sangat cepat. Menggunakan lebih sedikit, komentar yang lebih bermakna memberi masing-masing komentar Anda nilai lebih, dan pembaca lebih cenderung memperhatikan mereka yang Anda tulis.

Memilih nama yang bermakna untuk variabel dan fungsi Anda adalah penting. Nama yang dipilih dengan baik dapat menghilangkan kebutuhan akan komentar penjelasan di seluruh kode Anda. Dalam contoh Anda, $magicatau mungkin $kindOfMagicsepertinya nama yang lebih baik daripada $bigkarena menurut contoh Anda, itu adalah "jenis sihir" yang sedang diuji, bukan "besar" sesuatu.

Katakan sebanyak mungkin dalam kode. Simpan prosa untuk kasus-kasus yang membutuhkan lebih banyak penjelasan daripada yang bisa Anda tulis dalam kode.

Coba nama variabel penjelas

Komentar dapat menjadi sangat bagus, tetapi jika memungkinkan, buat kode untuk didokumentasikan sendiri. Salah satu cara untuk melakukan ini adalah dengan nama variabel penjelas. Misalnya, daripada ini:

if (user.has_sideburns && user.can_gyrate) {
  // This user is a potential Elvis impersonator

}

Saya lebih suka variabel bernama:

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}

Hanya untuk melengkapi beberapa komentar:

Penggunaan komentar yang tepat adalah untuk mengkompensasi kegagalan kami untuk mengekspresikan diri dalam kode. Perhatikan bahwa saya menggunakan kata gagal. Aku serius. Komentar selalu gagal. Kita harus memilikinya karena kita tidak bisa selalu mencari cara untuk mengekspresikan diri tanpa mereka, tetapi penggunaannya bukan merupakan alasan untuk perayaan. ( Clean Code oleh Robert C. Martin )

BTW: Saya merekomendasikan buku ini.

Komentar tidak boleh memparafrasekan kode tetapi menjelaskan hal-hal yang tidak ada dalam kode (gambaran yang lebih besar, mengapa, mengapa alternatif tidak dipilih ...) Dan contoh komentar Anda hanya itu: parafrase kode.

Anda mungkin kadang-kadang merasa bahwa parafrase diperlukan pada awal elsecabang, tetapi itu sering merupakan pertanda bahwa thencabang Anda terlalu besar.

Dalam contoh spesifik Anda, komentar mungkin tidak diperlukan. Seperti yang disebutkan Caleb , jika kode ditulis dengan jelas dan variabel memiliki nama semantik, jika pernyataan cenderung membutuhkan komentar.

Bandingkan cuplikan Anda dengan ini:

if ($x) {
    func1();
} else {
    func2();
}

Dalam hal ini, Anda pasti ingin menggunakan komentar untuk menggambarkan apa yang mewakili x, func1, dan func2 (dan menampar orang yang menamakan sesuatu dengan skema itu, terutama jika itu Anda). Anda bahkan tidak tahu apakah $xseharusnya boolean. Tetapi ini juga merupakan kasus di mana Anda tidak perlu berkomentar, jika Anda dapat melakukan refactor dan mengganti nama.

Secara umum, saya suka menulis komentar untuk blok logis yang menjelaskan hal-hal yang tidak bisa dilakukan sendiri oleh kode. Satu baris setiap ~ 10-20 baris yang menggambarkan apa yang dicapai beberapa baris berikut pada satu tingkat abstraksi yang lebih tinggi (misalnya // Make the right amount of magic happenuntuk contoh Anda) akan membantu Anda tetap berorientasi dan memberikan wawasan pengulas baru tentang apa yang Anda lakukan dan kapan .

Saya sebenarnya sering menulis ini satu-baris sebelum saya mulai menulis kode, sehingga saya tidak kehilangan jejak yang seharusnya dimiliki segmen.

Akhirnya, jika Anda benar-benar lebih suka (atau ada mandat yang mengharuskan) mengomentari klausa di blok if terlepas dari keterbacaan kode, saya sarankan:

// Broad description of block
if (something) {
    //Do this because something
    something();
} else {
    //Do this because !something
    somethingElse();
}

Saya merasa ini yang terbersih, karena komentar berbaris dengan kode yang berkaitan. Sebuah komentar yang menjelaskan kode apa yang harus dilakukan sedekat mungkin dengan komentar yang digambarkannya mungkin.

if (IsWeekDay(day))
{// weekday -> alarm at 7am
   ...
}
else if(day == DayOfWeek.Saturday)
{// saturday -> alarm at 11am
   ...
}
else
{// (sunday) -> no alarm
   ...
}

Saya menjaga tanda kurung saya dan meletakkannya tepat setelah braket.

[Condition] -> [pseudo-code]

Di sisi lain, secara teknis berarti semua kondisi lain gagal, jadi saya biasanya menggunakan tanda kurung.

([Condition]) -> [pseudo-code]

Catatan: ini untuk C #.

Saya mencoba dan menggunakan komentar di dalam blok yang mengatakan apa yang dilakukan oleh blok itu (sampel pertama Anda).

Di mana ini agak rusak adalah ketika menggunakan elseif. Saya menggunakan Basic sehingga tidak ada blok akhir yang eksplisit dan sering harus mengomentari kondisi apa yang memeriksa pada baris di atas (dengan jeda baris tentu saja) jika terlalu panjang.

'Check XYZ
If Condition1 then
  'We need to do T and S
  DoCodeFor1();

'Check ABC
ElseIf Condition1 then
  'This requires something else to be done
  DoCodeFor2()

Else
  'We have no other option than to...
  DoCodeFor3()

End If

• Jagalah agar blok persyaratan Anda tetap pendek.
• Panggil metode dengan nama deskriptif yang bagus jika sepertinya kode kondisional Anda akan lebih dari satu atau dua baris sederhana.
• Gunakan nama deskriptif yang bagus untuk variabel Anda.
• Pastikan pernyataan kondisional jelas artinya, dan tidak dikaburkan atau panjang. Gunakan metode jika itu membantu menjaga hal-hal bersih dan mudah dibaca.

Jika semua hal di atas gagal, tambahkan komentar deskriptif yang sangat kecil sebelum pernyataan if, untuk memperjelas maksud Anda. Kalau tidak, tidak perlu ada komentar sama sekali.

Dalam C ++ atau C # Saya biasanya tidak akan berkomentar kasus sederhana (ketika jelas apa yang terjadi), dan menggunakan gaya semacam ini untuk mengomentari final lain ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}