Bad comments are bad. For example c

Bad comments are bad. For example comments which only explains what can be trivially seen from the code, the classical example being:

// increment x by one
x++;
Comments which explains something which could be made clear by renaming a variable or method or otherwise restructuring the code, is a code smell:

// data1 is the collection of tasks which failed during execution
var data1 = getData1();
These are the kind of comments Martin rails against. The comment is a symptom of a failure to write clear code - in this case to use self-explanatory names for variables and methods. The comment itself is of course not the problem, the problem is we need the comment to understand the code.

But comments should be used to explain everything which is not obvious from the code, e.g. why the code is written a certain non-obvious way:

// need to reset foo before calling bar due to a bug in the foo component.
foo.reset()
foo.bar();
Comments which explains what an overly convoluted piece of code does is also a smell, but the fix is not to outlaw comments, the fix is the fix the code! In the real word, convoluted code does happen (hopefully only temporarily until a refactor) but no ordinary developer writes perfect clean code the first time. When convoluted code happens it is much better to write a comment explaining what it does than not write a comment. This comment will also make it easier to refactor later.

Sometimes code is unavoidably complex. It may be an complicated algorithm, or it may be code sacrificing clarity for performance reasons. Again comments are necessary.

ผลลัพธ์ (ไทย) 1:

ความคิดเห็นที่ไม่ดีไม่ดี ตัวอย่างเช่นข้อคิดเห็นซึ่งเพียง อธิบายอะไรจะ trivially ได้จากรหัส ตัวอย่างคลาสสิกถูก:เพิ่มค่า x โดยx ++ความคิดเห็นที่อธิบายบางสิ่งบางอย่างซึ่งอาจจะทำได้ชัดเจนจากการเปลี่ยนชื่อตัวแปรหรือวิธีการ หรือการปรับโครงสร้างรหัส มิฉะนั้น จะกลิ่นรหัส:ของสินค้า 1 คือกลุ่มของงานที่ล้มเหลวในระหว่างการดำเนินการของสินค้า 1 var = getData1()เหล่านี้เป็นชนิดของข้อคิดเห็นมาร์ตินราวกับ ความคิดเห็นเป็นอาการของความล้มเหลวการเขียนโค้ดชัดเจน - ในกรณีนี้จะใช้ชื่อตัวแปรและวิธีอธิบายตนเอง ความคิดเห็นตัวเองไม่ได้แน่นอนปัญหา ปัญหาคือ เราต้องคิดเพื่อทำความเข้าใจรหัสแต่ข้อคิดเห็นควรใช้การอธิบายที่ไม่ชัดเจนจากรหัส เช่น ทำไมรหัสจะเขียนวิธีการบางอย่างไม่ชัดเจน:ต้องรีเซ็ตฟูก่อนเรียกบาร์เนื่องจากการจุดบกพร่องในคอมโพเนนต์ฟูfoo.reset()foo.bar()ความคิดเห็นที่อธิบายสิ่งที่เป็นชิ้นส่วนที่ซับซ้อนมากเกินไปของรหัสไม่ มีกลิ่น แต่การแก้ไขจะไม่ท้องความเห็น การแก้ไขคือ การแก้ไขรหัส คำจริง รหัสที่ซับซ้อนเกิดขึ้น (หวังว่าเพียงชั่วคราวจนกว่าการ refactor) แต่เขียนรหัสสะอาดเหมาะสำหรับนักพัฒนาที่ไม่ธรรมดาครั้งแรก เมื่อรหัสที่ซับซ้อนเกิดขึ้นก็จะเขียนความเห็นอธิบายสิ่งที่มันไม่ดีกว่าไม่เขียนความคิดเห็น ความคิดเห็นนี้ยังจะให้มันง่ายต่อการ refactor ภายหลังบางครั้งรหัสซับซ้อนหลีกเลี่ยงไม่ได้ อาจเป็นอัลกอริทึมซับซ้อน หรืออาจจะสูญเสียความคมชัดทางรหัส อีก ความคิดเห็นจำเป็น

ผลลัพธ์ (ไทย) 2:

ความคิดเห็นที่ไม่ดีที่ไม่ดี สำหรับความคิดเห็นของตัวอย่างซึ่งจะอธิบายถึงสิ่งที่สามารถมองเห็นได้นิด ๆ จากรหัสตัวอย่างคลาสสิกเป็น: // เพิ่มขึ้น x โดยหนึ่งX ++ ความคิดเห็นซึ่งจะอธิบายบางสิ่งบางอย่างซึ่งอาจจะทำให้เห็นได้ชัดโดยการเปลี่ยนชื่อตัวแปรหรือวิธีการหรือมิฉะนั้นการปรับโครงสร้างรหัสที่เป็น กลิ่นรหัส: // data1 เป็นคอลเลกชันของงานที่ล้มเหลวระหว่างการดำเนินการvar data1 = getData1 (); เหล่านี้เป็นชนิดของความคิดเห็นมาร์ตินรางกับ แสดงความคิดเห็นเป็นอาการของความล้มเหลวในการเขียนโค้ดชัดเจน - ในกรณีนี้จะใช้ชื่อตัวอธิบายสำหรับตัวแปรและวิธีการ แสดงความคิดเห็นของตัวเองเป็นหลักสูตรที่ไม่ได้เป็นปัญหาที่เป็นปัญหาที่เราต้องแสดงความคิดเห็นที่จะเข้าใจรหัส. แต่ความเห็นควรจะใช้เพื่ออธิบายทุกอย่างซึ่งไม่ได้เป็นที่เห็นได้ชัดจากรหัสเช่นทำไมรหัสถูกเขียนทางที่ไม่ชัดเจนบางอย่าง : // จำเป็นต้องตั้งค่าก่อนที่จะเรียก foo บาร์เนื่องจากข้อผิดพลาดในคอมโพเนนต์ foo ได้. foo.reset () foo.bar (); ความคิดเห็นซึ่งจะอธิบายสิ่งที่เป็นชิ้นส่วนที่ซับซ้อนมากเกินไปของรหัสที่ไม่ยังเป็นกลิ่น แต่การแก้ไขคือ ไม่ได้ห้ามแสดงความคิดเห็นการแก้ไขคือการแก้ไขรหัส! ในคำจริงรหัสที่ซับซ้อนจะเกิดขึ้น (หวังเพียงชั่วคราวจนกว่า refactor) แต่ไม่มีนักพัฒนาสามัญเขียนรหัสสะอาดที่สมบูรณ์แบบเป็นครั้งแรก เมื่อรหัสที่ซับซ้อนที่เกิดขึ้นมันเป็นเรื่องที่ดีมากเพื่อเขียนความคิดเห็นอธิบายสิ่งที่มันไม่กว่าไม่ได้เขียนความคิดเห็น ความคิดเห็นนี้ยังจะทำให้ง่ายต่อการ refactor ภายหลัง. บางครั้งรหัสที่มีความซับซ้อนหลีกเลี่ยงไม่ได้ มันอาจจะเป็นอัลกอริทึมที่มีความซับซ้อนหรือมันอาจจะเป็นรหัสเสียสละความชัดเจนเพื่อเหตุผลด้านประสิทธิภาพ อีกครั้งการแสดงความคิดเห็นเป็นสิ่งที่จำเป็น