เมื่อใดก็ตามที่ฉันเขียนภาษาอื่นถ้าสร้างในภาษาใดฉันสงสัยว่าอะไรจะเป็นวิธีที่ดีที่สุด (ในแง่ของการอ่านและภาพรวม) เพื่อเพิ่มความคิดเห็น โดยเฉพาะอย่างยิ่งเมื่อแสดงความคิดเห็นข้ออื่นความคิดเห็นมักจะออกจากสถานที่สำหรับฉัน สมมติว่าเรามีโครงสร้างเช่นนี้ (ตัวอย่างถูกเขียนลงใน PHP):

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

ฉันสามารถแสดงความคิดเห็นได้เช่นนี้

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

หรือ

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

หรือ

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

ตัวอย่างวิธีปฏิบัติที่ดีที่สุดของคุณสำหรับการแสดงความคิดเห็นคืออะไร

ฉันชอบ:

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

หรือ:

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();
}

ดูเหมือนว่าโง่เล็กน้อยที่จะเขียนความคิดเห็นอธิบายสิ่งที่สภาพของคุณตรวจสอบยกเว้นว่ารหัสไม่ได้ระบุอย่างชัดเจน ยิ่งไปกว่านั้นควรเขียนรหัสใหม่เพื่อให้ชัดเจนที่สุด เช่นเดียวกันกับเนื้อหาของบล็อกที่มีเงื่อนไข - หากคุณสามารถทำให้เหตุผลในการทำสิ่งที่ชัดเจนให้ทำเช่นนั้นแทนการแสดงความคิดเห็น

ฉันไม่ได้สมัครสมาชิกกับปรัชญา "ไม่เขียนความคิดเห็น" แต่ฉันเชื่อว่าในการหลีกเลี่ยงความคิดเห็นที่บอกว่าควรจะพูดถึงโค้ดใด หากคุณเขียนความคิดเห็นเช่น "ตรวจสอบสิ่งที่วิเศษควรเกิดขึ้น" เมื่อโค้ดสามารถบอกได้ว่าif ($magic == big) {...ผู้อ่านจะหยุดอ่านความคิดเห็นของคุณอย่างรวดเร็ว การใช้ความคิดเห็นที่มีความหมายน้อยลงทำให้ความคิดเห็นของคุณมีค่ามากขึ้นและผู้อ่านมีแนวโน้มที่จะใส่ใจกับสิ่งที่คุณเขียนมากขึ้น

การเลือกชื่อที่มีความหมายสำหรับตัวแปรและฟังก์ชั่นของคุณเป็นสิ่งสำคัญ ชื่อที่ได้รับการแต่งตั้งอย่างดีสามารถกำจัดความต้องการคำอธิบายที่อธิบายได้ทั่วทั้งรหัสของคุณ ในตัวอย่างของคุณ$magicหรืออาจ$kindOfMagicดูเหมือนชื่อที่ดีกว่า$bigตามตัวอย่างของคุณมันคือ "ชนิดของเวทมนต์" ที่ถูกทดสอบไม่ใช่ "ความเย้ายวนใจ" ของบางสิ่ง

พูดมากที่สุดเท่าที่คุณสามารถในรหัส บันทึกร้อยแก้วสำหรับกรณีที่ต้องการคำอธิบายมากกว่าที่คุณสามารถเขียนเป็นรหัสได้

ลองชื่อตัวแปรอธิบาย

ความคิดเห็นนั้นยอดเยี่ยม แต่ถ้าเป็นไปได้ให้ทำการจัดทำโค้ดด้วยตนเอง วิธีหนึ่งในการทำเช่นนี้คือชื่อตัวแปรที่อธิบายได้ ตัวอย่างเช่นมากกว่านี้:

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

}

ฉันต้องการตัวแปรชื่อ:

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}

เพียงเพื่อแสดงความคิดเห็น:

การใช้ความคิดเห็นที่เหมาะสมคือการชดเชยความล้มเหลวของเราในการแสดงรหัสของเราเอง โปรดทราบว่าฉันใช้คำว่าล้มเหลว ฉันหมายถึงมัน. ความคิดเห็นมักจะล้มเหลว เราต้องมีพวกเขาเพราะเราไม่สามารถหาวิธีแสดงออกได้โดยปราศจากพวกเขา แต่การใช้งานของพวกเขาไม่ใช่สาเหตุของการเฉลิมฉลอง ( ทำความสะอาดรหัสโดย Robert C. Martin )

BTW: ฉันแนะนำหนังสือเล่มนี้

ความคิดเห็นไม่ควรถอดความรหัส แต่อธิบายสิ่งที่ไม่ได้อยู่ในรหัส (ภาพที่ใหญ่กว่าทำไมเลือกไม่เลือก ... ) และตัวอย่างความคิดเห็นของคุณก็คือ: การถอดความของรหัส

บางครั้งคุณอาจรู้สึกว่าจำเป็นต้องถอดความเมื่อเริ่มต้นelseสาขา แต่นั่นมักเป็นสัญญาณว่าthenสาขาของคุณใหญ่เกินไป

ในตัวอย่างเฉพาะของคุณความคิดเห็นอาจไม่จำเป็น ในฐานะที่เป็นคาเลบกล่าวถึง , ถ้ารหัสเขียนไว้อย่างชัดเจนและตัวแปรมีชื่อความหมายถ้างบมีโอกาสน้อยที่จำเป็นในการแสดงความคิดเห็น

เปรียบเทียบตัวอย่างของคุณกับสิ่งนี้:

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

ในกรณีนี้คุณต้องการใช้ความคิดเห็นเพื่ออธิบายว่า x, func1 และ func2 หมายถึงอะไร (และตบผู้ที่ตั้งชื่อสิ่งต่าง ๆ ตามรูปแบบนั้นโดยเฉพาะอย่างยิ่งถ้าเป็นคุณ) คุณไม่สามารถบอกได้ว่า$xควรจะเป็นบูลีนหรือไม่ แต่นี่ก็เป็นกรณีที่คุณไม่จำเป็นต้องมีความคิดเห็นถ้าคุณสามารถ refactor และเปลี่ยนชื่อ

โดยทั่วไปแล้วฉันชอบเขียนความคิดเห็นสำหรับบล็อกเชิงตรรกะที่อธิบายถึงสิ่งที่โค้ดไม่สามารถทำได้ด้วยตนเอง หนึ่งซับทุกบรรทัด ~ 10-20 ที่อธิบายสิ่งต่อไปนี้ไม่กี่บรรทัดที่ประสบความสำเร็จในระดับที่สูงกว่าหนึ่งนามธรรม (เช่น// Make the right amount of magic happenตัวอย่างของคุณ) จะช่วยให้คุณมุ่งเน้นและให้ความเห็นผู้ตรวจทานใหม่ในสิ่งที่คุณทำและเมื่อ .

จริงๆแล้วฉันมักจะเขียนหนึ่ง liners ก่อนที่ฉันจะเริ่มเขียนโค้ดเพื่อที่ฉันจะได้ไม่พลาดการไหลของเซ็กเมนต์ที่ควรจะมี

ท้ายที่สุดถ้าคุณชอบ (หรือมีคำสั่งที่ต้องการ) การแสดงความคิดเห็นใน if if โดยไม่คำนึงถึงความสามารถในการอ่านของรหัสฉันขอแนะนำ:

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

ฉันรู้สึกว่ามันสะอาดที่สุดเพราะความคิดเห็นสอดคล้องกับรหัสที่เกี่ยวข้อง ความคิดเห็นที่อธิบายว่าโค้ดใดควรใกล้เคียงกับความคิดเห็นที่อธิบายได้มากที่สุด

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

ฉันเก็บวงเล็บของฉันไว้และวางไว้ด้านหลังวงเล็บ

[Condition] -> [pseudo-code]

ในทางอื่นมันหมายถึงเงื่อนไขอื่น ๆ ทั้งหมดล้มเหลวดังนั้นฉันมักจะใช้วงเล็บ

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

หมายเหตุ: นี่สำหรับ C #

ฉันลองและใช้ความคิดเห็นภายในบล็อกบอกว่าบล็อกนั้นทำอะไร (ตัวอย่างแรกของคุณ)

เมื่อไรที่การแบ่งประเภทนี้ใช้เมื่อelseifใด ฉันใช้เบสิคดังนั้นจึงไม่มีบล็อกเอนด์ที่ชัดเจนและมักจะต้องแสดงความคิดเห็นว่าเงื่อนไขใดที่กำลังตรวจสอบซึ่งไปที่บรรทัดด้านบน (แน่นอนว่ามีตัวแบ่งบรรทัด) ถ้ามันยาวเกินไป

'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

• ทำให้บล็อกตามเงื่อนไขของคุณสั้นจริงๆ
• เรียกเมธอดที่มีชื่อที่สื่อความหมายได้ดีถ้ามันดูเหมือนว่าโค้ดที่มีเงื่อนไขของคุณจะเป็นมากกว่าสองหรือสามบรรทัด
• ใช้ชื่อที่สื่อความหมายได้ดีสำหรับตัวแปรของคุณ
• ตรวจสอบให้แน่ใจว่าคำสั่งเงื่อนไขมีความชัดเจนในความหมายของมันและไม่ยุ่งเหยิงหรือยาว ใช้วิธีการถ้าช่วยรักษาความสะอาดและอ่านได้

หากทั้งหมดข้างต้นล้มเหลวให้เพิ่มความคิดเห็นเชิงอธิบายที่เล็กมากก่อนคำสั่ง if เพื่อชี้แจงเจตนาของคุณ ไม่อย่างนั้นไม่จำเป็นต้องแสดงความคิดเห็นเลย

ใน C ++ หรือ C # ฉันมักจะไม่แสดงความคิดเห็นกรณีง่าย ๆ (เมื่อมันชัดเจนว่าเกิดอะไรขึ้น) และใช้รูปแบบนี้สำหรับการแสดงความคิดเห็นสุดท้าย ...

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