คุณคิดอย่างไรกับ Periods / Full Stops ในคอมเม้นท์โค้ด [ปิด]

ฉันเห็นสิ่งนี้ถามใน SO Tavernดังนั้นฉันจึงโพสต์คำถามที่นี่ ฉันคิดว่ามันเป็นคำถามที่น่าสนใจ (แน่นอนว่ามันไม่ได้อยู่ในนั้น แต่ฉันคิดว่ามันโอเคที่นี่)

คุณเพิ่มจุด (หรือตามที่ OP เขียนว่า "full stop") ในความคิดเห็นเกี่ยวกับโค้ดของคุณหรือไม่

เพื่อให้มันเกี่ยวข้องทำไม ?

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

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}

ใช่เพราะความคิดเห็นเป็นภาษาอังกฤษและภาษาอังกฤษที่เหมาะสมใช้เครื่องหมายวรรคตอน

คุณเพิ่มจุด (หรือตามที่ OP เขียนว่า "full stop") ในความคิดเห็นเกี่ยวกับโค้ดของคุณหรือไม่

เพื่อให้มันเกี่ยวข้องทำไม?

ด้วยเหตุผลเดียวกันฉันเพิ่มพวกเขาเมื่อเขียนข้อความ "ปกติ" - พวกเขาเป็นส่วนหนึ่งของภาษาในการเขียนและไม่ควรมีอะไรพิเศษเกี่ยวกับพวกเขา ฉันใช้พวกเขาอย่างเท่าเทียมกันเมื่อเขียนความคิดเห็นหนึ่งประโยค (หนึ่งบรรทัด) รวมทั้งย่อหน้า

ซอร์สโค้ดไม่ใช่ข้อความปกติดังนั้นเราจึงใช้กฎที่แตกต่างกัน ง่าย ;-)

หากคุณเขียนความเห็นจะหวังว่าพวกเขาจะเขียนเป็นภาษาอังกฤษ ในกรณีนี้เราควรเว้นวรรคอย่างถูกต้อง การทำอย่างอื่นจะขี้เกียจ

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

บางครั้งฉันก็บ้าไปแล้วและใช้เครื่องหมายอัศเจรีย์, เครื่องหมายคำถาม ฯลฯ )

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

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

จุดที่อาจเกี่ยวข้องก็คือการหลีกเลี่ยงเครื่องหมายอัศเจรีย์, โดยเฉพาะอย่างยิ่งทวีคูณ ตัวอย่าง:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

และ

    // This code really sucks!

ในทางกลับกันเครื่องหมายคำถามนั้นค่อนข้างมีประโยชน์ในบางครั้ง:

    // TODO: What does Crojpler.bway() actually do?

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

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

ตัวอย่างจริงจากรหัสของฉัน:

ความคิดเห็นบันทึกด่วน:

// check for vk_enter

เอกสารวิธีการ "เหมาะสม":

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.

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

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

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