เอกสารรหัสก่อน? [ปิด]

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

ใช่.

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

นอกจากนี้ยังง่ายต่อการแก้ไขบางสิ่งบางอย่างบนกระดานวาดภาพมากกว่าใน IDE

มีวิธีคิดอยู่สองวิธี:

1) เอกสารเช่นเดียวกับในเอกสาร Word, Wiki ฯลฯ โดยคำจำกัดความคุณไม่สามารถมีเอกสารรหัสที่สมบูรณ์เพราะคุณไม่มีรหัสไปยังเอกสาร คุณสามารถลองจัดทำเอกสารการออกแบบระดับสูง, สมมติฐาน, อินเทอร์เฟซและสัญญาก่อน

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

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

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

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

แก้ไข: เอกสารบางอย่าง แต่ควรทำตามที่คุณไปนาน ทำให้ง่ายต่อการทำเอกสารฉบับเต็มในภายหลัง

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

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

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

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

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

สิ่งที่เลวร้ายที่สุดที่คุณสามารถทำได้ - และฉันเคยเห็นสิ่งนี้เกิดขึ้น - คุณได้คนฉลาดมากมายเข้าห้องทำงานเป็นเวลาหกเดือนและเขียนข้อกำหนดระบบ 247 หน้าก่อนที่พวกเขาจะเข้าใจว่ามันคืออะไร พยายามที่จะสร้าง เพราะหลังจากหกเดือนพวกเขาจะมีระบบที่เจาะจงมากซึ่งอาจไร้ประโยชน์ และบ่อยครั้งที่พวกเขาพูดว่า“ เราทุ่มเงินลงทุนมากในสเป็คที่เราต้องสร้างมันขึ้นมา” ดังนั้นพวกเขาจึงสร้างระบบที่ไร้ประโยชน์และไม่เคยใช้ และนั่นก็น่ากลัว หากคุณไม่ได้ใช้เคสคุณสร้างสิ่งนั้นจากนั้นลองทำอะไรที่ง่าย ๆ และคุณก็รู้ว่า“ โอ้เอ้ยเอ้ยทำอะไรง่าย ๆ อย่างการหยิบเอกสาร XML และพิมพ์มันต้องใช้หน้ากระดาษสำเร็จรูป รหัส." และนั่นเป็นสิ่งที่น่ากลัว

- Joshua Bloch จากการสัมภาษณ์ใน " Coders at Work: Reflections on Craft of Programming " โดย Peter Seibel

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

บางคนถึงกับไปไกลกว่านี้และระบุว่า บริษัท ควรจะทำงานถอยหลังอย่างสมบูรณ์ดังนั้น

1. เขียนข่าวประชาสัมพันธ์
2. เขียนคำถามที่พบบ่อย
3. กำหนดประสบการณ์ของลูกค้า
4. เขียนคู่มือผู้ใช้
5. เริ่มการเขียนโปรแกรม

ดู http://www.allthingsdistributed.com/2006/11/working_backwards.html

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

README ไม่ได้จัดทำเอกสารรายละเอียดทุกโครงการของคุณ โดยทั่วไปจะมีข้อมูลต่อไปนี้แทน:

1. คำอธิบาย : สั้น "ระยะห่างระหว่างการขาย" บอกผู้อ่านว่าทำไมพวกเขาควรอ่านต่อไป
2. ตัวอย่างด่วน : ตัวอย่างรหัสสั้น ๆ หรือภาพหน้าจอเพื่อสนับสนุนคำอธิบาย
3. เริ่มต้นอย่างรวดเร็ว : วิธีเริ่มต้นใช้งานติดตั้งคำแนะนำและตัวอย่างเพิ่มเติม
4. เอกสารเพิ่มเติม : ลิงก์ไปยังเอกสารฉบับเต็มและข้อมูลเพิ่มเติม
5. การจัดระเบียบโครงการ : ใครคือผู้เขียน, วิธีการมีส่วนร่วม, วิธีการยื่นข้อบกพร่อง
6. ประกาศทางกฎหมาย : ใบอนุญาตลิขสิทธิ์และรายละเอียดทางกฎหมายอื่น ๆ

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

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

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

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

สำหรับข้อมูลเพิ่มเติมตรวจสอบสิ่งต่อไปนี้:

1. การพัฒนา Readme ขับเคลื่อน
2. รหัสที่สำคัญที่สุดไม่ใช่รหัส
3. คุณเป็นเอกสารของคุณ

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

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