“ ความคิดเห็นเป็นกลิ่นรหัส” [ปิด]

ผู้ร่วมงานของผมเชื่อว่าการใด ๆ ที่ใช้ในการแสดงความคิดเห็นรหัส (เช่นไม่ใช่วิธีการรูปแบบ Javadoc หรือระดับความคิดเห็น) เป็นกลิ่นรหัส คุณคิดอย่างไร?

เฉพาะในกรณีที่ความคิดเห็นอธิบายสิ่งที่รหัสกำลังทำอยู่

หากฉันต้องการทราบว่าเกิดอะไรขึ้นในวิธีการหรือบล็อกฉันจะอ่านรหัส ฉันหวังว่านักพัฒนาที่ทำงานในโครงการที่กำหนดนั้นอย่างน้อยก็คุ้นเคยกับภาษาการพัฒนาเพื่ออ่านสิ่งที่เขียนและเข้าใจสิ่งที่กำลังทำอยู่

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

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

อย่างไรก็ตามสิ่งที่สำคัญที่สุดคือการเปลี่ยนความคิดเห็นของคุณเมื่อคุณเปลี่ยนรหัสของคุณ หากคุณเปลี่ยนอัลกอริทึมตรวจสอบให้แน่ใจว่าได้อัปเดตความคิดเห็นด้วยเหตุผลที่คุณไปกับอัลกอริธึม X บน Y ความคิดเห็นที่เก่าเกินไปเป็นกลิ่นรหัสที่ใหญ่กว่า

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

เพื่อนร่วมงานของคุณมีประสบการณ์ไม่เพียงพอ

ความคิดเห็นควรอธิบายว่าทำไมไม่ใช่อย่างนั้น

Howความคิดเห็นประเภทมักจะดีกว่าจัดการกับการใช้ refactoring โดยส่วนตัวแล้วฉันมักจะหลีกเลี่ยงความคิดเห็นเพื่อสนับสนุนการปรับโครงสร้างใหม่

ก่อน:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

หลังจาก:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

ฉันขอประกาศเพื่อนร่วมงานของคุณว่าเป็นคนนอกรีต! รองเท้าบู๊ ธ ของคนนอกรีตของฉันอยู่ที่ไหน

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

ความเห็นจริงจากรหัสที่ฉันใช้:

    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

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

สิ่งที่คุณควรหลีกเลี่ยงอย่างยิ่งคือ "รหัสความคิดเห็นซ้ำซ้อน" (ความคิดเห็นที่ไม่ได้เพิ่มโค้ดใด ๆ ลงในโค้ด):

i++; // Increment i by 1

จากนั้นหากมีการออกแบบและจัดทำโค้ด (และดูแลรักษา / จัดตำแหน่ง) ที่ดีการแสดงความคิดเห็นนั้นมีประโยชน์น้อยกว่า

แต่ในบางสถานการณ์ความคิดเห็นสามารถช่วยอ่านโค้ดได้ดี:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

อย่าลืมว่าคุณต้องรักษาและซิงค์อย่างต่อเนื่องเช่นกันความคิดเห็น ... ความคิดเห็นที่ล้าสมัยหรือผิดอาจเป็นความเจ็บปวดที่น่ากลัว! และตามกฎทั่วไปการแสดงความคิดเห็นมากเกินไปอาจเป็นอาการของการเขียนโปรแกรมที่ไม่ดี

การกำหนดวิธีการหรือกระบวนการอย่างชัดเจนในฐานะ "รหัสกลิ่น" คือ "กลิ่น zealotry" คำนี้กำลังกลายเป็น "การพิจารณาที่เป็นอันตราย" ใหม่

โปรดจำไว้ว่าสิ่งเหล่านี้ควรเป็นแนวทาง

คำตอบอื่น ๆ อีกมากมายให้คำแนะนำที่ดีว่าควรให้ความคิดเห็นเมื่อใด

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

สร้างใหม่ทุกอย่างจนกว่าเด็กอนุบาลจะเข้าใจว่ามันไม่ได้เป็นการใช้เวลาอย่างมีประสิทธิภาพและอาจจะไม่ทำงานเช่นเดียวกับเวอร์ชั่นที่กระชับกว่า

ความคิดเห็นไม่ส่งผลกระทบต่อเวลาทำงานดังนั้นปัญหาเชิงลบเดียวที่ต้องพิจารณาคือการบำรุงรักษา

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

  response.contentType="text/html"
  render '{"success":true}'

ดูแปลกใช่ไหม? น่าจะเป็นข้อผิดพลาดในการคัดลอกวาง? ร้องหาข้อผิดพลาดหรือไม่?

ตอนนี้เหมือนกันกับความคิดเห็น:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler

ปัญหาหลักที่นี่คือความหมายของคำว่า "รหัสกลิ่น"

หลายคน (รวมถึงคุณด้วยฉันคิดว่า) เข้าใจถึงกลิ่นของรหัสเพื่อเป็นสิ่งที่ใกล้เคียงกับข้อผิดพลาดหรืออย่างน้อยสิ่งที่ต้องได้รับการแก้ไข บางทีคุณคิดว่ามันเป็นคำพ้องกับ "anti-pattern"

นี่ไม่ใช่ความหมายของคำว่า!

การเปรียบเทียบกลิ่นรหัสนั้นมาจากWards Wikiและพวกมันเน้น:

โปรดทราบว่า CodeSmell เป็นคำใบ้ว่ามีบางอย่างผิดปกติไม่ใช่เรื่องที่แน่นอน สำนวนที่ดีอย่างสมบูรณ์อาจได้รับการพิจารณาว่าเป็น CodeSmell เพราะมักใช้ในทางที่ผิด การเรียกสิ่งที่ CodeSmell ไม่ใช่การโจมตี มันเป็นเพียงสัญลักษณ์ที่จะรับประกันได้ว่า

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

นั่นคือความหมายสำหรับความคิดเห็นที่จะมีกลิ่นรหัส

แก้ไข: ฉันเพิ่ง stumpled บทความเหล่านี้สองซึ่งอธิบายได้ดีกว่าฉัน:

• ขอโทษในรหัส
• ต้องการความคิดเห็น

ฉันคิดว่ากฎนั้นค่อนข้างง่าย: ลองนึกภาพคนแปลกหน้ารหัสของคุณ คุณอาจจะเป็นคนแปลกหน้าในรหัสของคุณเองใน 5 ปี พยายามลดความพยายามทางจิตให้เข้าใจรหัสของคุณสำหรับคนแปลกหน้านี้

ความคิดที่ดีที่จะมีความคิดเห็นที่ถูกต้องคือการเริ่มต้นด้วยการเขียนความคิดเห็น

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

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

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

สำหรับสิ่งที่ไม่สามารถแยกออกได้อย่าแยกวิธีการและพิมพ์รหัสใต้ความคิดเห็น

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

หากมีการใช้พารามิเตอร์มากเกินไปก็ควรเป็นสมาชิกส่วนตัวในชั้นเรียนของคุณ

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

// Dear me in the future. Please, resolve this problem.

หรือ

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.

ความคิดเห็นเกี่ยวกับโค้ดไม่ใช่ "กลิ่นรหัส" อย่างแน่นอน โดยทั่วไปแล้วความเชื่อนี้มาจากความจริงที่ว่าความคิดเห็นอาจกลายเป็นสิ่งล้าสมัยและล้าสมัย อย่างไรก็ตามการมีความคิดเห็นที่ดีซึ่งอธิบายว่าทำไมรหัสกำลังทำบางสิ่งบางอย่างในวิธีที่สามารถ (และมักจะ) สำคัญสำหรับการบำรุงรักษา

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

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

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

Sams สอนตัวเอง Visual C # 2010 ใน 24 ชั่วโมงหน้า 348-349

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

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

การกล่าวถึงอันทรงเกียรติคือรูปแบบการต่อต้าน:

มันเป็นความประทับใจของฉันที่บางครั้งตัวอย่างใบอนุญาต FLOSS มักถูกใช้แทนเอกสารไฟล์ GPL / BSDL สร้างข้อความที่ดีและหลังจากนั้นคุณมักจะเห็นบล็อกแสดงความคิดเห็นอื่น ๆ

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

ความคิดเห็นควรอธิบายถึงเจตนาของรหัสเพื่อที่ว่าหากมีข้อผิดพลาดบางคนที่อ่านความคิดเห็น + รหัสจะมีโอกาสค้นพบมัน

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

ความคิดเห็นที่ใส่ในเพราะมีคนคิดว่ามันโอเคที่จะมี 700 บรรทัดในวิธีการหนึ่งเป็นกลิ่น

ความคิดเห็นที่มีเพราะคุณรู้ว่าถ้าคุณไม่ได้ใส่ความคิดเห็นใครบางคนจะทำผิดพลาดเหมือนเดิมอีกครั้งเป็นกลิ่น

ความคิดเห็นที่ใส่ไว้เนื่องจากเครื่องมือวิเคราะห์รหัสบางอย่างต้องการมันก็เป็นกลิ่น

คนที่ไม่เคยแสดงความคิดเห็นหรือเขียนแม้แต่ความช่วยเหลือเล็กน้อยสำหรับนักพัฒนารายอื่นก็เป็นกลิ่น ฉันประหลาดใจที่มีคนจำนวนมากที่ไม่เขียนเรื่องลง แต่จะหันหลังกลับและยอมรับว่าพวกเขาจำไม่ได้ว่าพวกเขาทำอะไรเมื่อ 3 เดือนก่อน ฉันไม่ชอบเขียนเอกสาร แต่ฉันอยากบอกคนอื่น ๆ ซ้ำแล้วซ้ำอีกแม้แต่น้อย

ฉันจะตอบด้วยคำถามของฉันเอง คุณพบข้อผิดพลาดในโค้ดที่ไม่ใส่เครื่องหมายด้านล่างหรือไม่

tl; dr: บุคคลต่อไปในการรักษารหัสของคุณอาจไม่เหมือนพระเจ้าอย่างที่คุณเป็น

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55

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

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

นอกจากนี้ความคิดเห็นมีประโยชน์มากในการเพิ่ม "caveats" เช่น "ระวัง! หากรูปแบบของอินพุตไม่ใช่ ASCII รหัสนี้จะต้องเปลี่ยน!"

การอ่านสิ่งนี้ฉันนึกถึงบางสิ่งที่ฉันได้อ่านเป็นครั้งแรก (จากรายชื่อที่นานกว่านั้นเก็บรักษาไว้โดยการถ่ายสำเนา) หลายทศวรรษมาแล้ว:

โปรแกรมเมอร์จริงไม่ได้เขียนความคิดเห็น - ถ้ามันยากที่จะเขียนมันควรอ่านยาก

กลิ่นเหม็นที่ค่อนข้างเก่ากว่า

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

แต่สิ่งที่จะพูดเกี่ยวกับกระบวนการที่ไม่สำคัญเช่นนี้? ดังนั้นคุณจะจบลงด้วยการเขียนคลาสสิก

i++; // add one to the "i" counter.

เพียงเพื่อให้ได้เกรดที่เหมาะสมและหากคุณมีอะไรเลยให้สร้างความเห็นที่ต่ำมากของความคิดเห็นโค้ด

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

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

ความเห็นของหลักสูตรมีกลิ่นรหัส ...

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

"ทำเช่นนี้!" ผู้จัดการโครงการของคุณพูดว่า

คุณตอบว่า "ไม่สามารถทำได้"

พวกเขาพูดว่า "จากนั้นเราจะหาคนอื่นทำ"

คุณพูดว่า "โอเคเอาละอาจจะทำได้"

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

1) ผู้ที่ทำงานของตนเองได้ง่ายขึ้นโดยจัดทำเป็นเอกสารอ้างอิงในอนาคตแสดงความคิดเห็นว่ากิจวัตรที่ล้มเหลวนั้นไม่ได้ผล (กลิ่นไม่ได้ลบทิ้งหลังจากค้นหางานที่ทำได้) หรือทำลายรหัสด้วยคำวิจารณ์ การจัดรูปแบบเพื่อหวังว่าจะทำให้การอ่านหรือทำความเข้าใจง่ายขึ้น อย่างจริงจังฉันไม่สามารถตำหนิพวกเขา แต่ในท้ายที่สุดพวกเขาตะครุบแล้วคุณมีสิ่งนี้: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) ผู้ที่ไม่ได้มีทั้งทำท่าจะเป็นซูเปอร์ฮีโร่หรืออาศัยอยู่ในถ้ำ พวกเขาไม่ใส่ใจต่อผู้อื่นด้วยตนเองโดยประมาทและสามารถใส่ใจน้อย ๆ เกี่ยวกับรหัสหรือความหมายที่อาจมีในภายหลัง

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

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

1. คุณต้องทำอะไรเป็นกรณี ๆ ไปและไม่มีเหตุผลที่ดีสำหรับมัน
2. รหัสอาจมีการเปลี่ยนแปลงในหนึ่งหรือสองปีเมื่อมีการเปลี่ยนแปลงกฎหมายและคุณต้องการค้นหาอีกครั้งอย่างรวดเร็ว
3. มีคนแก้ไขรหัสในอดีตเพราะพวกเขาไม่เข้าใจว่ารหัสกำลังทำอะไรอยู่

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

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

ดังนั้นการเขียนความคิดเห็นจึงเป็นเรื่องยากพอ ๆ กับการสื่อสารของมนุษย์! ผู้เขียนควรมีแนวความคิดที่ชัดเจนว่าผู้ชมคือใครและควรใช้ข้อความประเภทใด คุณจะรู้ได้อย่างไรว่าใครจะอ่านความคิดเห็นของคุณในอีกสิบยี่สิบปี? ถ้าบุคคลนั้นมาจากวัฒนธรรมที่แตกต่างอย่างสิ้นเชิง เป็นต้นฉันหวังว่าทุกคนจะเข้าใจสิ่งนี้

แม้ในวัฒนธรรมเล็ก ๆ ที่ฉันอาศัยอยู่มันก็แค่ยากที่จะสื่อสารความคิดกับคนอื่น ๆ การสื่อสารของมนุษย์มักจะล้มเหลวยกเว้นโดยบังเอิญ

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

อีกเหตุผลเดียวที่ฉันโรยความคิดเห็นลงในรหัสคือการเรียกสิ่งที่ดูเหมือนจะไม่สมเหตุสมผล

ความคิดเห็นเหล่านั้นมักจะอยู่ในรูปแบบของสิ่งที่ชอบ:

//xxx what the heck is this doing??

หรือ

// removed in version 2.0, but back for 2.1, now I'm taking out again

การให้ความคิดเห็นเกี่ยวกับโค้ดหากเป็นไปได้หน่วยของข้อโต้แย้งฟังก์ชันและการส่งคืนฟิลด์โครงสร้างแม้แต่ตัวแปรในเครื่องก็มีประโยชน์มาก จำยานอวกาศ Mars!

นี่คือกฎของหัวแม่มือของฉัน:

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

ให้ความรู้แก่เพื่อนร่วมงานของคุณเกี่ยวกับเทคนิคการเขียนโปรแกรมวรรณกรรม

ไม่ความคิดเห็นไม่ใช่กลิ่นรหัส แต่เป็นเครื่องมือที่สามารถถูกทำร้ายได้

ตัวอย่างของความคิดเห็นที่ดี :

// ฉันคิดว่านี่เป็นหน่วยเซนติเมตร จำเป็นต้องมีการสอบสวนเพิ่มเติม!

// นี่เป็นวิธีที่ฉลาดในการทำ X

// รายการนี้รับประกันว่าไม่ว่างที่นี่