วิธีการทำเอกสารสำหรับรหัสและทำไมซอฟต์แวร์ (มักจะ) เอกสารไม่ดี?

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

ในการ จำกัด การพัฒนาซอฟต์แวร์ทั้งหมดของฉันฉันต้องจัดการกับรหัสที่มีเอกสารไม่ดี ฉันสังเกตเห็นสิ่งต่าง ๆ ต่อไปนี้ -

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

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

ฉันได้เรียนรู้ว่าเอกสารไม่ได้รับความสนใจเนื่องจากมีเหตุผลดังต่อไปนี้:

1. ความเกียจคร้าน
2. นักพัฒนาไม่ต้องการทำอะไรนอกจากรหัส
3. งานรักษาความปลอดภัย. (หากไม่มีใครสามารถเข้าใจรหัสของคุณได้อย่างง่ายดายคุณอาจไม่สามารถเปลี่ยนได้อย่างง่ายดาย)
4. กำหนดเวลาที่ยากลำบากทำให้เสียเวลาเล็กน้อยในการจัดทำเอกสาร

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

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

มีวิธีที่จะจบหรือบรรเทาความบ้าคลั่งนี้หรือไม่? "การพัฒนาเอกสารขับเคลื่อน" อาจจะ?

รหัสเอกสารได้อย่างไร?

คุณมีคำใบ้อยู่แล้ว: ดูว่าเอกสาร API ของ Java มีอะไรบ้าง

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

เหตุใดโครงการโอเพนซอร์สหลายโครงการจึงไม่ได้รับการบันทึกไว้อย่างดี

เพราะโครงการโอเพ่นซอร์สส่วนใหญ่ทำโดยคนที่มีส่วนร่วมในโครงการเหล่านั้นเพราะมันสนุก โปรแกรมเมอร์และนักพัฒนาส่วนใหญ่พิจารณาว่าการเขียนเอกสารไม่สนุกพอที่จะทำฟรี

เหตุใดโครงการปิดแหล่งกำเนิดหลายโครงการจึงไม่ได้รับการบันทึกไว้อย่างดี

เนื่องจากมีค่าใช้จ่ายจำนวนมากในการ (1) เขียนเอกสารที่ดีและ (2) เก็บรักษาไว้

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

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

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

สิ่งที่ฉันมักสังเกตคือ:

1. ในตอนแรกทีมยินดีที่จะทำเอกสารมาก

2. เมื่อเวลาผ่านไปความกดดันของเส้นตายและการขาดความสนใจทำให้มันยากขึ้นในการรักษาเอกสาร

3. ไม่กี่เดือนต่อมาคนใหม่ที่เข้าร่วมโครงการในทางปฏิบัติไม่สามารถใช้เอกสารได้เพราะมันไม่สอดคล้องกับระบบจริง

4. สังเกตว่าฝ่ายจัดการโทษผู้พัฒนาว่าไม่ได้ดูแลเอกสาร นักพัฒนาขอให้ใช้เวลาสองสามสัปดาห์ในการอัปเดต

   • หากผู้บริหารให้เวลาสองสามสัปดาห์วงจรจะเกิดซ้ำ

   • หากฝ่ายบริหารปฏิเสธตามประสบการณ์ที่ผ่านมาจะเพิ่มประสบการณ์ที่ไม่ดีเนื่องจากผลิตภัณฑ์ไม่มีเอกสารประกอบ แต่ใช้เวลาสองสามเดือนในการเขียนและดูแล

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

วิธีส่งเสริมให้ทีมเขียนเอกสารประกอบ?

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

• นำโดยตัวอย่าง หากคุณเขียนเอกสารที่ดีคู่ของคุณอาจเริ่มทำเช่นกัน

• ทำการตรวจสอบโค้ดอย่างเป็นระบบรวมถึงการตรวจสอบโค้ดอย่างเป็นทางการที่มีเป้าหมายเพื่อตรวจสอบเอกสาร

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

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

• ใช้ gamification สิ่งนี้มาพร้อมกับประเด็นก่อนหน้า

• การใช้งานในเชิงบวก / เชิงลบการเสริมแรง

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

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

    /// <summary>
    /// Gets or sets the PrimaryHandling.
    /// </summary>
    public Workflow PrimaryHandling { get; set; }

ซึ่งก็อืม ... ไม่เป็นประโยชน์โดยเฉพาะอย่างยิ่ง

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

มีตัวอย่างที่ดีหรือไม่ที่จำเป็นต้องมีเอกสารน้อยที่สุด

เอกสารอธิบายสถาปัตยกรรมและการออกแบบไม่จำเป็นต้องใช้:

• สำหรับต้นแบบ

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

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

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

ฉันรู้สึกว่าเราควรมีการตรวจสอบเอกสารหลังจากส่งมอบโครงการ

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

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

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

TL; DR

หากคุณขอให้ทุกโครงการมีเอกสารที่ดีแสดงว่าคุณขอมากเกินไป