เอกสารเท่าไหร่เพียงพอหรือไม่


15

มีเอกสารด้านเทคนิค (สำหรับนักพัฒนาในอนาคต) เพียงพอหรือไม่ มีอัตราส่วนระหว่างการเข้ารหัสชั่วโมงและการบันทึกเวลาที่เหมาะสมหรือไม่?

Papadimoulis โต้แย้งว่าคุณควร

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

นั่นเป็นแนวทางที่ดีหรือมีสิ่งเฉพาะที่ฉันควรสร้างหรือไม่?


1
ผู้ใช้ / UI หรือเอกสารทางเทคนิค / รหัสต้นฉบับหรือไม่

2
สำหรับคำแนะนำเกี่ยวกับซอร์สโค้ดโปรดอ่านคำถามแรกของเว็บไซต์ของเรา: programmers.stackexchange.com/questions/1/…
Tamara Wijsman

คำตอบ:


24

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


1
+1 ฉันก็ชอบไอเดียนั้นด้วย พัฒนาซอฟต์แวร์ของคุณดังนั้นจึงไม่ต้องใช้เอกสารประกอบ

12

ความสมบูรณ์แบบของ La เป็นความภาคภูมิใจที่ไม่ได้เป็นบวกกับการแต่งตัวของฉัน, แต่ก็ไม่ได้เป็นบวกกับผู้แต่ง
Antoine de Saint-Exupéry

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

1
ดังนั้นโครงการที่ลบเอกสารทั้งหมดแล้วสมบูรณ์แบบใช่ไหม

@ ThorbjørnRavnAndersen - ไม่ความสมบูรณ์แบบสำเร็จเมื่อลบเนื้อหาใด ๆ เพิ่มเติมจะส่งผลเสียต่อมูลค่าของเอกสารโดยรวม
cjmUK

1
@cjmUK และการตีความนั้นตอบคำถามที่ถามอย่างไร

@ ThorbjørnRavnAndersen มันไม่ได้; มันเป็นความคิดเห็นในการตอบสนองต่อความคิดเห็นของคุณ - ซึ่งสำหรับบันทึกนั้นฉันสงสัยว่าเป็นการตีความที่ผิดของคำตอบของเบอนัวต์ เบอนัวต์เท่านั้นที่สามารถตอบได้อย่างแน่นอน อย่างไรก็ตามคำตอบของฉันอยู่ในรายการอื่น ...
cjmUK

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

3

ฉันกำลังคิดเกี่ยวกับหัวข้อนี้ในขณะที่

ข้อสรุปของฉันคือ - มันไม่ได้เป็นเรื่องของปริมาณ แต่คุณภาพและบริบท

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

ในทำนองเดียวกันการจำแนกเพื่อชี้แจงบริบทการตั้งชื่อ (ID ในผู้ป่วย -> ผู้ป่วย. ID)

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

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

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

ความสอดคล้องเป็นสิ่งที่สำคัญมากเช่นกัน - การประชุมโดยตัวมันเองนั้นไร้ประโยชน์หากมันไม่สอดคล้องกัน

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

ครึ่งต่อสู้เป็นความคุ้นเคย

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

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

ตัวอย่างเช่นคุณกำลังทำงานในอุตสาหกรรมการแพทย์ ในวิธีการของคุณคุณเขียน "IsPatientSecure = true;"

ตอนนี้โปรแกรมเมอร์ที่ดีคนใดสามารถคิดได้ว่าคนไข้ถูกทำเครื่องหมายว่าปลอดภัย แต่ทำไม ความหมายคืออะไร?

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

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


1

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

ฉันไม่รู้อัตราส่วนที่ดี

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

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


1

พอที่จะทำให้คุณหยุดเดาตัวเองครั้งที่สอง

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

ล้างซ้ำจนกว่าความรู้สึกนั้นจะหายไป


1
-1: คุณมักจะพูดว่า 'ehhhh ... ทำในสิ่งที่คุณรู้สึกเหมือน' ซึ่งเป็นคำตอบที่ไม่ใช่
Steven Evers

ดูเหมือนว่าเขาจะพูดว่า 'ทำทุกสิ่งที่คุณรู้สึกว่าจำเป็น' ซึ่งฟังดูเหมือนคำตอบที่ถูกต้องสำหรับฉัน ฉันจะระวังคำตอบที่เฉพาะเจาะจงมากเกินไป
cjmUK

1

ฉันพบว่าวิธีการที่ขับเคลื่อนด้วยความเสี่ยงเช่นที่นำเสนอในหนังสือของ George Fairbanks ' Just Enough Software Architecture นั้นทำงานได้ดีมากสำหรับการทำความเข้าใจว่ามีเอกสารเพียงพอเพียงใด คุณสามารถอ่านส่วนที่นำเสนอแนวคิดนี้ (บทที่ 3) บนเว็บไซต์ของเขา แต่แนวคิดหลักคือ:

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

เพื่อช่วยในการสอบเทียบข้อกังวลเพื่อให้คุณสามารถจัดลำดับความเสี่ยงได้ฉันพบว่ามีประโยชน์ในการระบุเป้าหมายที่เรียกว่าThreshold of Successซึ่งเป็นเป้าหมายขั้นต่ำที่ทีมของคุณคิดว่าเป็นโครงการที่ประสบความสำเร็จ จากมุมมองของเอกสารตัวอย่าง ToS อาจมีลักษณะเช่น "นักพัฒนาควรสามารถสร้างปลั๊กอินอย่างง่ายได้ภายใน 4 ชั่วโมงหลังจากรับเฟรมเวิร์กเป็นครั้งแรก"

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

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

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

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


1

น้อยที่สุดเท่าที่จะทำได้ แต่มากเท่าที่จำเป็น

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

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

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

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


0

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

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

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

โดยการใช้ไซต์ของเรา หมายความว่าคุณได้อ่านและทำความเข้าใจนโยบายคุกกี้และนโยบายความเป็นส่วนตัวของเราแล้ว
Licensed under cc by-sa 3.0 with attribution required.