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

เมื่อต้นเดือนที่โพสต์นี้ถูกสร้าง:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

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

ในตัวอย่างที่กำหนด

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

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

$extension = GetFileExtension($image_filename);

อย่างไรก็ตามในความคิดเห็นที่มีคนให้คำแนะนำนั้น:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

ผู้เขียนตอบโดยกล่าวว่าผู้วิจารณ์คือ "หนึ่งในคนเหล่านั้น" คือโปรแกรมเมอร์ที่ไม่ดี

ทุกคนมีความเห็นอย่างไรกับรหัสอธิบายตนเองเทียบกับรหัสความคิดเห็น?

ฉันชอบเขียนโค้ดด้วยตนเอง คำแนะนำสำหรับการนี้เป็นรหัสที่สะอาด

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

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

คุณไม่ควรจัดทำเอกสารสิ่งที่รหัสกำลังทำอยู่ แต่คุณควรจัดทำเอกสารสาเหตุที่ทำ

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

ความคิดเห็นอื่น ๆ ทั้งหมดสามารถกำจัดได้อย่างปลอดภัย

ฉันไม่เชื่อในรหัสอธิบายตนเอง มีโค้ดที่อ่านได้มากขึ้นและโค้ดที่อ่านได้น้อยขึ้นอยู่กับภาษาความรู้ของคุณ (ในฐานะผู้เขียนต้นฉบับ) ความรู้เกี่ยวกับผู้ชายที่อ่านมันและฟังก์ชันโค้ด แต่ไม่ยัง ... มันควรจะอธิบายด้วยความคิดเห็นสั้น ๆ

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

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

โชคดีที่ค่ายทั้งสองในการสนทนานี้มีตัวแทนอยู่ที่นี่และมีการกล่าวถึงข้อโต้แย้งทั้งด้านโปรและการต่อต้าน

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

อาร์กิวเมนต์ที่ทับซ้อนกัน

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

ตอนนี้ความแตกต่างที่สำคัญคือมีน้ำหนักเท่าไรในข้อโต้แย้งเหล่านั้น

รหัสอธิบายตนเอง

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

ความคิดเห็นเพิ่มเติม

• ความคิดเห็นสามารถอ่านได้มากกว่ารหัส ภาษาอังกฤษธรรมดาดีกว่าในการอธิบายบางสิ่งบางอย่าง

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

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

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

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

"ฉันขอโทษ แต่ผู้ชายคนนั้นของคุณ"

ฉันสงสัยว่าทำไมเขาถึงไม่แสดงความคิดเห็น: P

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

เงยหน้าขึ้นมองการเขียนโปรแกรมความรู้เป็นสไตล์ที่รุนแรง

คำตอบที่สั้นกว่าดีกว่าและถูกต้อง

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

คำตอบที่ดีกว่าความคิดเห็นควรใช้เพื่ออธิบายว่า "ทำไม" เท่านั้นความคิดเห็นควร:

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

คำอธิบายการสำรองข้อมูล

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

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

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

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

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

สิ่งที่มีรหัสการจัดทำเอกสารด้วยตนเองคือภายในฟังก์ชั่นนั้นคุณจะพบ:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

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

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

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

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

$ extension = GetFileExtension ($ image_name);

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

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

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

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

เพียงแค่พยายามไม่ฉลาดเพราะรหัสที่ฉลาดอ่านแล้วน่ากลัว คำหลัก: บำรุงรักษา !

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

หากคุณใช้ระบบควบคุมแหล่งข้อมูลคุณสามารถใช้ข้อความยืนยันเพื่อให้ทุกคน (และตัวคุณเอง) รู้ว่าคุณทำอะไรในเวลาที่กำหนดและที่สำคัญกว่านั้นคือสาเหตุ

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

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

EBITDA

และไม่

EquityBeforeInterestTaxesDepreciationAndAmortization

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

ฉันคิดว่าเราต้องแยกความแตกต่างระหว่างเอกสารและการแสดงออกของรหัส

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

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

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

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

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

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

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

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

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

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

เพียงแค่ใส่ไม่ได้เขียนว่าคุณเป็นความคิดเห็นรหัสพวกเขา

ลองดู Code Complete 2nd edition, pg 128-129

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

เอนทิตีในโลกแห่งความจริงมากกว่าการใช้งานในระดับต่ำ

คุณสามารถหลีกเลี่ยงการใช้ความคิดเห็น

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

ความคิดเห็นมีประโยชน์จริง ๆ เมื่อพวกเขาถูกตีความโดย IDE เกี่ยวกับวิธีการทำงานของ Delphi 2009+ หรือ JavaDoc แต่นั่นเป็นภาษามาร์กอัปที่มีโครงสร้างมากกว่าดังนั้นในแง่ที่คุณกำลังเขียนโปรแกรมเอกสารของคุณซึ่งฉลาดมาก

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

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

หากคุณจำเรื่องนี้ไว้ตอนเขียนโปรแกรม /?

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

ที่งานส่วนใหญ่ของฉันฉันมักจะต้องแก้ไขรหัสของคนอื่นและเขียนเอกสารที่แย่มากที่สุด

ดังนั้นนิสัยของคุณที่คิดว่ารหัสเอกสารนั้นเป็นของตัวเอง

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

ตรวจสอบhttp://thedailywtf.comพวกเขามีเรื่องราวที่ตลกขบขันมากมาย แต่เป็นเรื่องจริงเกี่ยวกับโปรแกรมเมอร์ที่เพิ่งไม่ได้ขยันเนื่องจาก ..