สำหรับความคิดเห็นในการควบคุมเวอร์ชันผู้ใช้คนอื่น ๆ ทำ / แนะนำอะไร - อดีตหรือปัจจุบันกาล?

กล่าวคือ

• เปลี่ยน x เป็น y
• หรือ
• เปลี่ยน x เป็น y

ความคิดเห็นควรอ่านในบริบทดังนั้น:

ปัจจุบัน

สำหรับความคิดเห็นต้นฉบับข้างต้นวิธีการหรือก่อนที่จะเกิดพฤติกรรมบางอย่าง:

// This function does X
function doX() { ... }

อดีต

สำหรับความคิดเห็นต้นฉบับหลังจากพฤติกรรมบางอย่างเกิดขึ้น

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

และสำหรับการส่งข้อความ

เปลี่ยนฟังก์ชั่น X

ตัวอย่างผสม:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

อดีต - เนื่องจากใครก็ตามที่อ่านในอนาคตจะอ้างถึงการเปลี่ยนแปลงที่เกิดขึ้นในอดีต

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

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

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

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

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

ฉันใช้กาลปัจจุบันที่จำเป็นดังนั้น:

เปลี่ยน "x" เป็น "y"

สิ่งนี้ถูกแนะนำโดยนักพัฒนา Git:

• ร่างกายควรจัดเตรียมข้อความการส่งข้อความที่มีความหมายซึ่ง:
  • ใช้ความจำเป็นปัจจุบันกาล: "การเปลี่ยนแปลง" ไม่ใช่ "การเปลี่ยนแปลง" หรือ "การเปลี่ยนแปลง"

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

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

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

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

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

คุณควรใช้อดีตกาล

เหตุผลที่คุณตอบคำถามนี้สิ่งใดที่ทำให้สำเร็จ? คิดว่าเป็นการบอก VCS ของคุณในสิ่งที่คุณทำ:

กระทำ 123
เปลี่ยน XYZ เพื่อทำ ABC

ในการยกตัวอย่างเคาน์เตอร์การใช้กาลอนาคตทำให้ดูเหมือนว่าคุณกำลังขอให้คนอื่นทำ:

กระทำ 123
เปลี่ยน XYZ เพื่อทำ ABC

และใช้เสียงที่มีอยู่ในปัจจุบันเหมือนว่าคุณผ่านไปครึ่งทางแล้ว:

กระทำ
การเปลี่ยน XYZ เป็น ABC

ใช้กาลปัจจุบัน: "เปลี่ยน X เป็น Y" เกือบราวกับว่ามันเป็นรายการในรายการสิ่งที่ต้องทำที่ชัดเจน

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

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

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

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

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

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

การป้อนข้อมูลได้รับการตรวจสอบแล้วก่อนที่จะเข้าบล็อกรหัสนี้

หรือ

ข้อมูลถูกเขียนไปยังไฟล์ในตอนท้ายของรหัสนี้จะถูกดำเนินการ

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

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

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

เมื่อเราย้ายฐานข้อมูลในที่สุดเราจะต้องเปลี่ยนตรรกะนี้

หรือ

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

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

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

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

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

  // Calculate the width of the curve at x height.
  

• ใช้ชุดคำหลักแบบตัวพิมพ์ใหญ่ทั้งหมดเพื่ออธิบายชุดรูปแบบทั่วไปในการเข้ารหัส (และเพื่อให้ง่ายต่อการค้นหา):

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>