ความคิดเห็นเป็นรูปแบบของเอกสารหรือไม่

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

จะไม่นี้:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

ได้รับการพิจารณาเอกสารโดยเฉพาะอย่างยิ่งหากนักพัฒนาซอฟต์แวร์กำลังใช้รหัสของฉันหรือไม่ หรือเอกสารประกอบนั้นถูกพิจารณาว่าอยู่นอกรหัสหรือไม่

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

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

พวกเขาเป็นรูปแบบของเอกสาร แต่จำไว้ว่าเอกสารนั้นอยู่ในสายตาของคนดู ....

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

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

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

• ถ้าผู้ใช้ขาดทักษะด้านเทคนิค แต่เพียงต้องการรู้ว่าเกิดอะไรขึ้นเอกสารของผู้ใช้คือสิ่งที่จำเป็น

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

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

ฉันรู้ว่าคุณหมายถึงมันเป็นตัวอย่างของการทิ้ง แต่สิ่งที่ชอบ

print $foo; # this prints "bar"

ไม่มีประโยชน์ มันเพิ่มความยุ่งเหยิงทางสายตา อย่าบันทึกเอกสารที่ชัดเจน

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

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

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

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

... อัตราส่วนของเวลาที่ใช้ในการอ่านและการเขียนดีกว่า 10: 1 เรากำลังอ่านรหัสเก่าอย่างต่อเนื่องซึ่งเป็นส่วนหนึ่งของความพยายามในการเขียนรหัสใหม่

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

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

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

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

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

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

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

3) สำหรับสคริปต์ตัวเลือก --help นี่คือที่ที่คุณสามารถไปหาเอกสารได้ ลองดูตัวอย่างคาดการณ์สิ่งที่ผู้ใช้ต้องการ

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