รหัสการจัดทำเอกสารด้วยตนเองคืออะไรและสามารถแทนที่รหัสที่มีเอกสารดีได้หรือไม่ [ปิด]

ฉันมีเพื่อนร่วมงานที่ยืนยันว่ารหัสของเขาไม่ต้องการความคิดเห็นมันเป็น "การทำเอกสารด้วยตนเอง"

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

ช่วยให้ฉันเข้าใจเขามุมมอง

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

อาจเป็นเพียงข้อ จำกัด ของตัวเอง แต่ฉันไม่เห็นว่ามันจะเป็นการปฏิบัติที่ดีได้อย่างไร

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

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

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

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

• เขียนความคิดเห็นเอกสาร (Doxygen, JavaDoc, ความคิดเห็น XML ฯลฯ ) สำหรับทุกระดับสมาชิกประเภทและวิธีการและ
• แสดงความคิดเห็นอย่างชัดเจนส่วนใด ๆ ของรหัสที่ไม่ใช่การจัดทำเอกสารด้วยตนเองและ
• เขียนข้อคิดเห็นสำหรับแต่ละบล็อคของรหัสที่อธิบายถึงเจตนาหรือสิ่งที่รหัสทำในระดับนามธรรมที่สูงขึ้น (เช่นค้นหาไฟล์ทั้งหมดที่มีขนาดใหญ่กว่า 10 MBแทนที่จะวนซ้ำผ่านไฟล์ทั้งหมดในไดเรกทอรีทดสอบว่าขนาดไฟล์ใหญ่กว่า 10 หรือไม่ MB, ผลตอบแทนผลตอบแทนถ้าเป็นจริง )

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

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

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

สำหรับรหัสการจัดทำเอกสารด้วยตนเองซึ่งแสดงสิ่งที่กำลังทำ:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

จากนั้นไปที่รหัสที่เป็นเอกสารซึ่งอธิบายได้ดีกว่าว่าทำไมมันถึงทำอยู่

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

และรุ่นสุดท้ายของรหัสเป็นเอกสารที่มีความคิดเห็นเป็นศูนย์ต้องการ:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

นี่คือตัวอย่างของสไตล์การแสดงความคิดเห็นที่ไม่ดี:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

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

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

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

มีคนเคยพูดว่า

1) เขียนเฉพาะความคิดเห็นสำหรับโค้ดที่เข้าใจยาก
2) พยายามอย่าเขียนโค้ดที่เข้าใจยาก

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

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

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

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

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

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

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

ฉันลืมที่ฉันได้รับจากนี้ แต่:

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

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

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

print "Hello, World!"

และนี่คือ:

factorial n = product [1..n]

และนี่คือ:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

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

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

รหัสการทำเอกสารด้วยตนเองเป็นตัวอย่างที่ดีของ "DRY" (อย่าทำซ้ำตัวเอง) อย่าทำซ้ำข้อมูลในความคิดเห็นซึ่งเป็นหรืออาจเป็นในรหัสเอง

แทนที่จะอธิบายว่าใช้ตัวแปรตัวใดให้เปลี่ยนชื่อตัวแปร

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

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

เป็นต้น

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

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

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

ความเห็นอาจมีประโยชน์มากสำหรับผู้มาใหม่หรือผู้ทดสอบหรือเพื่อสร้างเอกสาร / ไฟล์ช่วยเหลือ

รหัสการจัดทำเอกสารด้วยตนเอง + ความคิดเห็นที่จำเป็นจะช่วยในการช่วยเหลือผู้คนในทีมต่างๆ

ในการสั่งซื้อ:

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

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

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

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

เมื่อคุณทำการบำรุงรักษาข้อมูล backgorund เหล่านั้นมีความสำคัญมาก

แค่เกลือนิดหน่อย ...

สำหรับตัวอย่างให้พิจารณาตัวอย่างต่อไปนี้:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

ในตัวอย่างนี้คุณมีความคิดเห็น 5 บรรทัดต่อรหัส 3 บรรทัด ยิ่งกว่านั้น - ความคิดเห็นไม่เพิ่มอะไรที่คุณไม่สามารถมองเห็นได้ด้วยการอ่านโค้ด หากคุณมี 10 วิธีเช่นนี้คุณจะได้รับ 'ความคิดเห็นตาบอด' และไม่สังเกตเห็นวิธีการหนึ่งที่เบี่ยงเบนจากรูปแบบ

ถ้าแน่นอนรุ่นที่ดีกว่าน่าจะเป็น:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

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

ความแตกต่างระหว่าง "อะไร" และ "อย่างไร"

• คุณควรจัดทำเอกสาร "สิ่งที่" ประจำวัน
• คุณไม่ควรจัดทำเอกสารว่า "ทำอย่างไร" ยกเว้นกรณีพิเศษ (เช่นอ้างถึงเอกสารขั้นตอนวิธีเฉพาะ) ควรจัดทำเป็นเอกสารด้วยตนเอง

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

ใน บริษัท ที่ฉันทำงานโปรแกรมเมอร์คนหนึ่งติดอยู่ด้านบนสุดของจอภาพ

"จัดทำเอกสารรหัสของคุณเหมือนคนที่รักษามันไว้ว่าเป็นคนบ้าคลั่งที่รู้ว่าคุณอยู่ที่ไหน"

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

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

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

ฉันประหลาดใจที่ไม่มีใครนำเรื่อง " การเขียนโปรแกรมวรรณกรรม " ซึ่งเป็นเทคนิคที่พัฒนาในปี 1981 โดย Donald E. Knuth จาก TeX และ "The Art of Computer Programming" ชื่อเสียง

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

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

ฉันพบตัวอย่างบนเว็บของมัน: http://moonflare.com/code/select/select.nwหรือรุ่น HTML http://moonflare.com/code/select/select.html

หากคุณสามารถหาหนังสือของ Knuth ได้ในห้องสมุด (Donald E. Knuth, การเขียนโปรแกรมวรรณกรรม, Stanford, California: ศูนย์การศึกษาภาษาและข้อมูล, 1992, บันทึกการบรรยาย CSLI, หมายเลข 27) คุณควรอ่าน

นั่นคือรหัสเอกสารด้วยตนเองพร้อมเหตุผลและทั้งหมด แม้แต่ทำเอกสารที่ดีทุกอย่างอื่นเป็นเพียงความเห็นเป็นลายลักษณ์อักษรที่ดี :-)

ฉันต้องการเสนอมุมมองที่มากกว่าหนึ่งสำหรับคำตอบที่ถูกต้อง:

ซอร์สโค้ดคืออะไร? ภาษาการเขียนโปรแกรมคืออะไร

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

คุณควรอ่านสิ่งที่คุณเขียนหรือไม่

ซอร์สโค้ดไม่ได้เขียนด้วยภาษามนุษย์ มีการทดลองใช้ (เช่น FORTRAN) แต่ไม่ประสบความสำเร็จอย่างสมบูรณ์

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

ภาษาโปรแกรมส่วนใหญ่มีความซ้ำซ้อนเพื่อให้คอมไพเลอร์สามารถจับเราเมื่อเราไม่สอดคล้องกัน ภาษาอื่นใช้การอนุมานมากกว่าและพยายามกำจัดความซ้ำซ้อนนั้น

คอมพิวเตอร์ไม่ต้องการชื่อประเภทชื่อวิธีการและชื่อตัวแปร พวกเราถูกใช้เพื่อการอ้างอิง คอมไพเลอร์ไม่เข้าใจความหมายนั่นคือเพื่อให้เราใช้

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

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

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

สำหรับฉันนี่เป็นกฎที่ฉันพยายามทำตาม:

• รหัสควรเป็นเรื่องง่ายและชัดเจนในการอ่านมากที่สุด
• ความคิดเห็นควรให้เหตุผลในการตัดสินใจออกแบบเช่น: ทำไมฉันถึงใช้อัลกอริธึมหรือข้อ จำกัด ที่รหัสมีเช่น: ไม่ทำงานเมื่อ ... (สิ่งนี้ควรได้รับการจัดการในสัญญา / การยืนยันในโค้ด) (ปกติแล้ว ภายในฟังก์ชั่น / ขั้นตอน)
• เอกสารควรแสดงรายการการใช้งาน (การเรียกการรวม), ผลข้างเคียง, ค่าส่งคืนที่เป็นไปได้ มันสามารถสกัดจากรหัสโดยใช้เครื่องมือเช่น jDoc หรือ xmlDoc มันมักจะอยู่นอกฟังก์ชั่น / ขั้นตอน แต่ใกล้กับรหัสมันอธิบาย

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

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

อย่างไรก็ตามสิ่งที่สำคัญจริงๆในเอกสารก็คือสิ่งที่ไม่สามารถมองเห็นได้โดยตรงจากรหัส: เจตนาพื้นฐานข้อสันนิษฐานผลกระทบข้อ จำกัด ฯลฯ

ความสามารถในการระบุว่ารหัสทำ X จากภาพรวมที่รวดเร็วเป็นวิธีที่ง่ายกว่าความสามารถในการตรวจสอบว่ารหัสไม่ได้ทำ Y เขาจะต้องจัดทำเอกสาร Y ...

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

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

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

แก้ไข: ฉัน (และอาจเป็นคนอื่น ๆ ) น่าจะมีบทบัญญัติว่าแอประบบประมวลผลสัญญาณดิจิตอล (DSP) ควรได้รับการแสดงความคิดเห็นเป็นอย่างดี นั่นเป็นเพราะแอป DSP เป็นหลัก 2 สำหรับลูปที่ป้อนด้วยอาร์เรย์ของค่าและเพิ่ม / คูณ / ฯลฯ กล่าวว่าค่า ... เพื่อเปลี่ยนโปรแกรมที่คุณเปลี่ยนค่าในหนึ่งในอาร์เรย์ ... ต้องการความคิดเห็นสองสามข้อเพื่อบอกว่าอะไร คุณกำลังทำในกรณีนั้น;)

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

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

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

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

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

การสร้างแบบจำลองโดเมนที่ดี 
+ ชื่อที่ดี (รูปแบบวิธีการคลาส) 
+ ตัวอย่างรหัส (การทดสอบหน่วยจากกรณีการใช้งาน) 
= ซอฟต์แวร์การทำเอกสารด้วยตนเอง 

เหตุผลสองประการที่ทำให้ความคิดเห็นเพิ่มเติมนอกเหนือจากรหัสอาจชัดเจนกว่า:

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

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

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

BisectionSearch

binarySearch

BinaryChop

วิธีการทั้งสามนี้มาจากนักพัฒนาที่ได้รับการฝึกฝนใน 3 ทวีปที่ต่างกันทำสิ่งเดียวกัน โดยการอ่านความคิดเห็นที่อธิบายอัลกอริทึมเท่านั้นเราสามารถระบุการทำซ้ำในไลบรารีของเรา

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

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

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

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

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

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

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

ไม่ได้หมายความว่าไม่ควรใส่รหัส หมายความว่าความคิดเห็นควรให้เหตุผลว่าทำไมโค้ดถูกเขียนในลักษณะที่เป็น

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

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

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

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