วิธีการทำให้ codebase ขนาดใหญ่เข้าใจง่ายขึ้น

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

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

ตัวอย่างเช่น:

/*
 * PROGRAMMER'S NOTES:
 *
 * As stated in the documentation, the GamepadManager class 
 * reads joystick joystick input using SDL and 'parses' SDL events to
 * Qt signals.
 *
 * Most of the code here is about goofing around the joystick mappings.
 * We want to avoid having different joystick behaviours between
 * operating systems to have a more integrated user experience, since
 * we don't want team members to have a bad surprise while
 * driving their robots with different laptops.
 *
 * Unfortunately, we cannot use SDL's GamepadAPI because the robots
 * are interested in getting the button/axes numbers, not the "A" or
 * "X" button.
 *
 * To get around this issue, we created a INI file for the most common 
 * controllers that maps each joystick button/axis to the "standard" 
 * buttons and axes used by most teams. 
 *
 * We choose to use INI files because we can safely use QSettings
 * to read its values and we don't have to worry about having to use
 * third-party tools to read other formats.
 */

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

นี่มันเจ๋งมาก. ฉันขอให้นักพัฒนาซอฟต์แวร์ใช้เวลาและความพยายามในการทำสิ่งนี้มากขึ้น มัน:

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

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

coder ที่มีประสบการณ์สามารถสร้างการออกแบบที่ชัดเจนและเข้าใจได้ง่ายโดยไม่ต้องใช้เอกสารประกอบ แต่คุณเคยเห็นโปรแกรมประเภทนี้มากี่โปรแกรม?

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

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

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

ในที่สุดโครงสร้างของเอกสารควรเป็นมาตรฐานทั่วทั้งโครงการเพื่อให้ทุกคนสามารถพบได้ (มันเป็นระเบียบของเอกสารปีเตอร์ในเครื่องติดตามบั๊กซูในวิกิ, อลันใน readme และจอห์นในซอร์สโค้ด ... ) .

ฉันไม่เห็นด้วยว่านี่เป็นวิธีการที่ดีมากเนื่องจาก

1. เมื่อคุณ refactor โครงการของคุณย้ายวิธีการรอบ ๆ เอกสารแบ่ง

2. หากเอกสารไม่ได้รับการปรับปรุงอย่างถูกต้องจะทำให้เกิดความสับสนมากกว่าช่วยให้เข้าใจรหัส

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

ใช่การมีโครงสร้างไดเรกทอรีที่เหมาะสมจะช่วยได้แน่นอน

ฉันเป็นแฟนตัวยงของเอกสารการออกแบบระดับสูง - เขียนก่อนรหัสใด ๆ - ที่ให้ภาพรวมของการออกแบบและรายการของคลาสและทรัพยากร การออกแบบจากบนลงล่างทำให้สิ่งต่าง ๆ ง่ายขึ้นมาก - คุณอาจเป็น "เครื่องมือเกม -> ฮาร์ดแวร์ -> ตัวควบคุม -> จอยสติ๊ก"; ดังนั้นโปรแกรมเมอร์คนใหม่บอกว่า "แก้ไขปุ่ม 'a' บนตัวควบคุม 'xyz" อย่างน้อยที่สุดก็จะรู้ว่าจะเริ่มมองที่ใด

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

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

สิ่งที่จะรวมไว้ในเอกสารการออกแบบคือ;

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

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

• ปัจจัยพื้นฐาน
• ผลกระทบ
• ค่าคงที่
• เงื่อนไขการยกเว้น (พ่น)

กฎที่สำคัญที่สุดที่ฉันพบเพื่อให้ง่ายขึ้นสำหรับนักพัฒนาใหม่ในการทำความเข้าใจ codebase คือข้อตกลงที่สมบูรณ์แบบมีราคาแพง

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

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

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

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

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

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

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

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

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