คุณควรทำเอกสารทุกอย่างหรือแค่มากที่สุด?

22

ดูเหมือนว่าบิตของการขัดแย้งเรื่องทุกอย่างเอกสารรวมทั้ง "JavaBean" ไวยากรณ์ของ getters และ setters สำหรับเขตข้อมูล: คนบอกว่ามันไม่มีความจำเป็นที่ยาวนานและทำลายซ้ำแห้ง (ไม่ซ้ำตัวเอง) , ที่ประชุมตั้งชื่อควรจะอธิบายทุกอย่าง , และมันก็เป็นรหัส / เอกสาร บางครั้งข้อโต้แย้งเหล่านี้ทำงาน แต่ในบางครั้งคุณต้องจบเรื่องนี้:

ข้อความแสดงแทน

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

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

documentation

— TheLQ
แหล่งที่มา

3

ในระดับหนึ่งสิ่งนี้แสดงให้เห็นถึงปัญหาการตั้งชื่อเช่น getDate ควรเป็น getCreationDate หรือ getExpiryDate หรือสิ่งที่สมเหตุสมผลในโดเมน แน่นอนว่าการตั้งชื่อไม่ใช่ยาครอบจักรวาล

— jk

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

24

ทุกอย่างเอกสารที่ทำให้รู้สึกถึงเอกสาร

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

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

— Ryan Hayes
แหล่งที่มา

27

ประการแรกบันทึกทุกอย่างที่ไม่สมเหตุสมผล

— ysolik

1

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

— Ryan Hayes

1

@ysolik ฉันเห็นด้วย แต่ฉันคิดว่าเขาหมายถึง 'บันทึกทุกอย่างที่เหมาะสมกับเอกสาร'

— Alan Pearce

3

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

— ysolik

1

@ysolik โอ้มนุษย์นั่นจะเป็นโลกอุดมคติที่ดีที่สุด

— Ryan Hayes

8

เก็บเอกสารไว้จนกว่าคุณจะสามารถดูคนอื่นอ่านได้โดยไม่รู้สึกว่าจำเป็นต้องอธิบายอะไร

— แบรดคทา
แหล่งที่มา

6

สัปดาห์ที่ผ่านมามีบทความที่ดีเกี่ยวกับเอกสารมากกว่าที่ The Daily WTF ฉันคิดว่ามันพูดทุกอย่างดังนั้นฉันจะปล่อยให้ลิงค์:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

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

— Mike42
แหล่งที่มา

4

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

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

— ความผิดพลาด
แหล่งที่มา

4

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

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

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

— สำหรับ
แหล่งที่มา

ดูเพิ่มเติมที่: “ ความคิดเห็นมีกลิ่นรหัส”

— gnat

2

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

— JB King
แหล่งที่มา

1

กล่าวอย่างง่าย ๆ คือมีเอกสารเพื่อช่วยเหลือนักพัฒนาในตอนนี้และผู้ดูแลในอนาคต

ถ้าคุณจำ maxim ง่าย ๆ นั้นได้ระดับของเอกสารควรจะกำหนดตัวเองได้

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

— แอนดรู
แหล่งที่มา

0

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

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

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

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

— EDC
แหล่งที่มา