ฉันกำลังทำงานในโครงการ Arduino โดยใช้ Uno โครงการมีรหัสจำนวนมาก ฉันต้องการสร้างห้องสมุดและฉันสามารถแชร์ในภายหลังได้ ฉันควรทำตามแนวทางใดในขณะออกแบบห้องสมุด?
คำตอบ:
มีประเด็นมากมายที่คุณควรคำนึงถึงในขณะที่ออกแบบห้องสมุด ในขณะที่คุณอาจจะลงเอยด้วยการแบ่งปันงานของคุณกับผู้อื่นเป็นสิ่งสำคัญอย่างยิ่งที่จะทำตามรูปแบบการออกแบบที่สอดคล้องกัน โปรดทราบว่าผู้ใช้รายอื่นจะมีระดับทักษะแตกต่างกันมากดังนั้นออกแบบไลบรารีที่ใช้งานง่ายให้มากที่สุดเท่าที่จะทำได้
จัดทำแผนที่หมุดพื้นฐานที่ห้องสมุดของคุณคาดหวัง อย่าคงการจับคู่พินแบบคงที่ แต่อนุญาตให้ผู้ใช้ทำการเปลี่ยนแปลงได้ง่าย
หนึ่งในสิ่งแรกที่คุณควรตรวจสอบให้แน่ใจคือห้องสมุดของคุณทำงานอยู่ หากไม่ใช่ให้ระบุอย่างชัดเจน คุณไม่ต้องการเสียเวลากับการพยายามทำงานกับซอฟต์แวร์ที่เสียดังนั้นอย่าปล่อยให้คนอื่นทำเช่นนั้น
ระบุอย่างชัดเจนว่าบอร์ดใดที่ห้องสมุดได้รับการออกแบบมาเพื่อใช้ทดสอบและบอร์ดใดที่คาดว่าจะใช้งานได้ ระบุการสร้าง (เวอร์ชั่น) ของทุกบอร์ดที่กล่าวถึงที่นี่
สิ่งต่อไปคือคุณควรมีอินเตอร์เฟสที่ชัดเจน ไลบรารีการทำงานที่มีอินเตอร์เฟสที่ซับซ้อนนั้นน่าผิดหวัง วิธีนี้จะช่วยให้คุณใช้ห้องสมุดได้ในภายหลังและจะทำให้ผู้ใช้รายอื่นง่ายขึ้น นี่เป็นหนึ่งในประเด็นที่สำคัญที่สุดที่ควรคำนึงถึง
ไม่ว่าคุณจะทำตามวิธีการจากบนลงล่างหรือจากล่างขึ้นบนอินเทอร์เฟซควรจะชัดเจนในใจของคุณ ในวิธีการจากล่างขึ้นบนสิ่งนี้อาจและจะยาก แต่ไม่ควรเพิกเฉย มิฉะนั้นคุณจะต้องจบด้วยห้องสมุดที่ซับซ้อนมากเกินไปซึ่งอาจไม่สามารถใช้งานได้
หากคุณมีฟังก์ชั่นใด ๆ ที่ใช้คุณสมบัติพิเศษบางอย่างของบอร์ดตรวจสอบให้แน่ใจว่าฟังก์ชั่นเหล่านี้โดดเด่นพูดถึงใน readme และในความคิดเห็น
อาจมีบางสถานการณ์ที่คุณอาจต้องใช้การรอคอยที่ยุ่ง ฟังก์ชั่นดังกล่าวขึ้นอยู่กับลอจิกของโปรแกรมซึ่งอาจป้องกันการควบคุมการไหลปกติดังนั้นจึงก่อให้เกิดปัญหาในขณะที่อยู่ระหว่างการทำงานที่สำคัญ ลองใช้การขัดจังหวะหรืออัลกอริทึมอื่น ๆ ถ้าเป็นไปได้ ถ้าไม่เช่นนั้นให้ระบุเครื่องหมายของฟังก์ชั่นดังกล่าวไว้อย่างชัดเจน
ตรวจสอบให้แน่ใจว่าได้แสดงความคิดเห็นทุกการเปลี่ยนแปลงเล็กและใหญ่ที่คุณทำ เขียนความคิดเห็นยาว ๆ ที่ดีสำหรับฟังก์ชั่นสำคัญทั้งหมดและเล็กลงสำหรับผู้อื่น อธิบายอินเตอร์เฟสของคุณอย่างชัดเจนอาร์กิวเมนต์แต่ละตัวสิ่งที่มันทำและสิ่งที่ส่งคืน นี่เป็นงานพิเศษจำนวนมาก แต่จะเป็นประโยชน์อย่างมากสำหรับทั้งคุณและคนอื่น ๆ หากคุณมีฟังก์ชั่นที่ไม่สามารถใช้งานได้กับบอร์ดอื่นให้พูดถึงที่นี่ หากสิ่งเหล่านี้เป็นฟังก์ชั่นระดับกลางที่มีการใช้งานโดยฟังก์ชั่นอื่น ๆ และอาจจำเป็นต้องพูดถึงใน Readme
ตรวจสอบให้แน่ใจว่าทุกอย่างแม้กระทั่งความคิดเห็นมีความสอดคล้องกันทั่วทั้ง.hและ.cppไฟล์
เก็บเฉพาะฟังก์ชันที่เกี่ยวข้องภายในไฟล์เดียว มีขนาดเล็ก แต่มีความสอดคล้องเชิงตรรกะโมดูลดีกว่าไฟล์ขนาดใหญ่หนึ่งไฟล์พร้อมทุกสิ่งในนั้น
เขียนไฟล์ readme ที่ชัดเจนซึ่งอธิบายถึงไลบรารีความสามารถของมันปัญหาหรือข้อบกพร่องใด ๆ และการใช้งานขั้นพื้นฐาน ใช้ไฟล์แยกต่างหากสำหรับการกำหนดและอธิบายแต่ละอินเตอร์เฟสตามที่อธิบายไว้ข้างต้น
เมื่อห้องสมุดมีขนาดใหญ่ขึ้นก็อาจจำเป็นต้องแบ่งเป็นไดเรกทอรี นี้ไม่ได้เป็นไปได้อย่างง่ายดายในขณะที่ใช้Arduino IDE- แต่ถ้าคุณไปถึงที่นี่คุณอาจเป็นผู้ใช้ Arduino ขั้นสูงและใช้เครื่องมือพัฒนาที่ทรงพลังกว่า ถ้าไม่ใช่นี่คือจักรวาลที่บอกให้คุณทำ
โปรดเพิ่มใบอนุญาต
ใช้เครื่องมือ VCS เช่น Git หรือ SVN สิ่งนี้จะทำให้การดูการเปลี่ยนแปลงทำได้ง่ายขึ้นกลับไปเป็นเวอร์ชันเก่าตรวจพบจุดผิดพลาดที่ทำให้เกิดรหัสและยังทำงานร่วมกับผู้อื่นได้
คำตอบของ AshRj นั้นดีมาก - ฉันมีเพียง 2 คะแนนเพื่อเพิ่มเข้าไป
จุดที่ 1: เอกสารประกอบ
AshRj แนะนำให้เขียน readme แบบละเอียด แม้ว่านี่จะเป็นวิธีปฏิบัติที่ดี แต่ก็สามารถออกไปจากห้องสมุดขนาดใหญ่ได้อย่างรวดเร็ว - แน่นอนแม้ว่าจะมีไม่กี่พันบรรทัด (ซึ่งไม่มากจริงๆ) readme จะแทบไม่มีประโยชน์ คำแนะนำของฉันจะไปอีกขั้นหนึ่งและใช้เทียบเท่า Javadocs สำหรับ C ++ - ตามคำตอบนี้ (อยู่ใน Stack Overflow) Doxygen เป็นเครื่องมือที่มีประโยชน์มากสำหรับการจัดการเอกสารและมือ (ไม่มีใครต้องการแก้ไข ไฟล์ readme line 10K ... )
จุดที่ 2: ไดเรกทอรี
อีกครั้งกับคำตอบที่ตัดกัน AshRj ของมักจะใช้ไดเรกทอรี แม้ว่าคุณจะมีเพียง 10 ไฟล์บางทีแม้จะมีเพียงแค่ 7 หรือ 8 ฉันรู้ว่ามันฟังดูโง่นิดหน่อย แต่มันเป็นงานพิสูจน์อนาคตของคุณและถ้าคุณไม่เริ่มต้นเร็วคุณจะต้องยุ่งกับ ไฟล์ ไดเรกทอรีที่ไม่ได้เป็นเพียงแค่สำหรับโครงการขนาดใหญ่ - ขนาดเล็กควรใช้พวกเขาเช่นกัน เพียงจำไว้ว่าใน C ++ (ภาษา Arduino de-พฤตินัย) ไดเรกทอรีจะถูกละเว้นเมื่อรวมไฟล์จากห้องสมุด - พวกเขาอยู่เป็นเครื่องมือการจัดการรหัสเท่านั้น