ทำไมไม่มีรหัสภาพรวมสำหรับโครงการโอเพ่นซอร์ส [ปิด]

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

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

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

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

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

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

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

ความจริงที่แห้งแล้งและรุนแรง

ไม่มีการจัดทำเอกสารเนื่องจากโครงการสามารถทำได้โดยไม่ต้องมีเอกสาร

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

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

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

แม้กระทั่งผู้จัดการโครงการอาจเลือกที่จะไม่สร้างเอกสาร

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

สิ่งที่มักจะเกิดขึ้นคือ:

1. มีการจัดทำเอกสารแนะนำเบื้องต้นเกี่ยวกับโครงการและสถานที่ที่จะไป (แผนงาน "ที่มีชื่อเสียง")
2. หากเป็นไปได้จะมีการพัฒนา API และเลือกให้เป็น "รหัสที่เป็นเอกสาร" เหนือส่วนใหญ่ของรหัสพื้นฐาน
3. โดยเฉพาะอย่างยิ่ง API แต่ยังมีรหัสอื่น ๆ ที่ถูกจัดรูปแบบและ "PHPdoc" / "Javadoc" ฯลฯ มีการเพิ่มข้อคิดเห็นพิเศษ พวกเขาเสนอการประนีประนอมที่ดีระหว่างเวลาที่ใช้ไปกับการให้รางวัล: แม้แต่โปรแกรมเมอร์ที่มีความถ่อมใจก็มักจะรู้วิธีการเขียนซับหนึ่งที่อธิบายถึงการทำงานของเขาพารามิเตอร์ได้รับการจัดทำเอกสาร "อัตโนมัติ" เช่นกัน desyncing "และ lagging behing development
4. บ่อยครั้งที่ฟอรัมถูกสร้างขึ้น มันเป็นสื่อโซเชียลที่ทรงพลังที่ผู้ใช้และโปรแกรมเมอร์อาจพูดคุยกัน (และระหว่างเพื่อนของพวกเขาอาจเป็นใน subforums "devs only") สิ่งนี้จะช่วยให้ความรู้จำนวนมากเกิดขึ้นอย่างช้าๆและได้รับการรวบรวมโดยชุมชนที่สร้างขึ้น (อ่าน: ไม่ได้ชั่งน้ำหนักในทีมนักพัฒนา) คำถามที่พบบ่อยและ HOWTO
5. ในโครงการขนาดใหญ่จริง ๆ ก็มีการผลิตวิกิ ฉันระบุว่า "โครงการขนาดใหญ่" เพราะพวกเขามักจะเป็นผู้ที่มีผู้ติดตามมากพอที่จะสร้างวิกิ (dev ทำ) และจากนั้นเติมจริงเกินกว่า "กระดูกเปลือย" (ชุมชนทำ)

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

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

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

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

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

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

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

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

เพราะมีโปรแกรมเมอร์โอเพ่นซอร์สมากกว่านักเขียนด้านเทคนิคโอเพนซอร์ซ

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

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

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

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

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

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

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

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

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

เพียงชื่อหนึ่งที่นิยมมาก: bluez ขอให้โชคดีในการหาบทช่วยสอนที่ดีนอกจากนี้เพื่อสแกนหาอุปกรณ์ใกล้เคียง