แสดงความคิดเห็นก่อนหรือหลังรหัสที่เกี่ยวข้อง [ปิด]

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

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

ดังนั้นโปรแกรมเมอร์ / สคริปเตอร์ส่วนใหญ่จะใส่ความคิดเห็นไว้ที่ใด: ก่อนหรือหลังรหัส?

หากคำตอบของคุณใช้ได้เฉพาะกับภาษาที่ระบุโปรดระบุว่า

และถ้าคุณสามารถอ้างอิงสเป็คที่ยอมรับหรือคำแนะนำที่สนับสนุนคำตอบของคุณได้ดียิ่งขึ้น

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

Microsoft กล่าวว่าเป็นวิธีการเขียนโปรแกรมที่ดีในการเริ่มต้นโพรซีเดอร์ด้วยความคิดเห็นเล็กน้อย (พวกเขาไม่ได้พูดถึงการแสดงความคิดเห็นหลังจากขั้นตอน) MSDN ลิงก์เกี่ยวกับ VisualBasic แต่ใช้กับภาษาการเขียนโปรแกรมส่วนใหญ่ฉันคิดว่า

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

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

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

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

ดังนั้นโปรแกรมเมอร์ / สคริปเตอร์ส่วนใหญ่จะใส่ความคิดเห็นไว้ที่ใด: ก่อนหรือหลังรหัส?

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

ข้อยกเว้นเพียงอย่างเดียวที่ฉันสามารถนึกได้คือความคิดเห็นที่ทำเครื่องหมายจุดสิ้นสุดของส่วนที่ถูกกล่าวถึงก่อนหน้านี้เช่นนี้:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

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

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

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

// this workaround is required to make the compiler happy
int i = 0;

เมื่อเทียบกับ

int i = 0; // make the compiler happy

แต่ไม่เคย:

int i = 0;
// this workaround is required to make the compiler happy

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

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

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

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

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

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

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

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

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

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

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

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

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

[blank line]
/* comment */
{ code }
[blank line]

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

[blank line]
{ code }
/* comment */
[blank line]

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

ความคิดเห็นด้านบนนั้นดีที่สุด

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

รหัสสามารถ (และควร) เป็น "การจัดทำเอกสารด้วยตนเอง" แต่ถ้าคุณต้องอ่านและทำความเข้าใจรหัสทุกบรรทัดเพื่อทำความเข้าใจว่าวิธีการทำงานอย่างไร If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

เมื่อฉันเกี่ยวกับหัวข้อนี้ฉันพบว่าระบบเอกสารที่คอมพิวเตอร์สามารถอ่านได้ (Doc XML, Doxygen, Java doc ฯลฯ ) ส่วนใหญ่คาดหวังว่าข้อคิดเห็นจะมาก่อนรหัสที่เกี่ยวข้อง

ฉันเห็นด้วยกับหัวข้อ SO - เราควรจะเพิ่มความคิดเห็นหลังจากบล็อกรหัสมากกว่าก่อนหรือไม่ ..

ฉันก็อยากจะรู้ล่วงหน้า ...

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

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

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