Tôi đang làm việc trên một dự án Arduino bằng Uno. Dự án chứa một lượng mã đáng kể. Tôi muốn tạo một thư viện và thậm chí tôi có thể chia sẻ nó sau này. Tôi nên làm theo hướng dẫn nào trong khi thiết kế thư viện?
Câu trả lời:
Có rất nhiều điểm mà bạn nên ghi nhớ trong khi thiết kế thư viện. Như bạn có thể, cuối cùng chia sẻ công việc của bạn với người khác, điều cực kỳ quan trọng là phải tuân theo các mẫu thiết kế nhất quán. Hãy nhớ rằng những người dùng khác sẽ có các cấp độ kỹ năng cực kỳ khác nhau, vì vậy hãy thiết kế một thư viện dễ sử dụng, ở mức độ tối đa có thể.
Cung cấp một bản đồ pin cơ bản mà thư viện của bạn đang mong đợi. Không giữ bản đồ pin tĩnh nhưng cho phép người dùng thực hiện các thay đổi dễ dàng.
Một trong những điều đầu tiên mà bạn nên cố gắng đảm bảo là thư viện của bạn đang hoạt động. Nếu không, hãy nói rõ như vậy. Bạn sẽ không muốn lãng phí thời gian của mình khi cố gắng làm việc với phần mềm bị hỏng, vì vậy đừng để người khác làm như vậy.
Đề cập rất rõ ràng (các) bảng mà thư viện được thiết kế, trên đó đã được thử nghiệm và bảng nào được dự kiến sẽ hoạt động. Chỉ định thế hệ (phiên bản) của mỗi bảng được đề cập ở đây.
Điều tiếp theo là bạn nên có giao diện được xác định rõ ràng. Một thư viện làm việc với các giao diện phức tạp là bực bội. Điều này sẽ giúp bạn tự sử dụng thư viện sau này và sẽ giúp mọi người dùng dễ dàng hơn. Đây phải là một trong những khía cạnh quan trọng nhất cần ghi nhớ.
Cho dù bạn theo cách tiếp cận từ trên xuống hay từ dưới lên, các giao diện phải luôn rõ ràng trong tâm trí của bạn. Theo cách tiếp cận từ dưới lên, điều này có thể và sẽ khó, nhưng không nên bỏ qua. Nếu không, bạn sẽ kết thúc với một thư viện quá phức tạp mà có thể không sử dụng được.
Nếu bạn có bất kỳ chức năng nào sử dụng một số đặc điểm bảng đặc biệt, hãy đảm bảo làm cho các chức năng này nổi bật, đề cập trong readme và cả trong các bình luận.
Có thể có những tình huống mà bạn có thể phải sử dụng một sự chờ đợi bận rộn. Các chức năng như vậy, tùy thuộc vào logic chương trình, có thể ngăn luồng điều khiển bình thường, do đó gây ra sự cố trong khi đang thực hiện một nhiệm vụ quan trọng. Cố gắng sử dụng ngắt hoặc các thuật toán khác, nếu có thể. Nếu không, sau đó đề cập rõ ràng đánh dấu bất kỳ chức năng như vậy.
Hãy chắc chắn để tiếp tục bình luận mỗi thay đổi lớn và nhỏ bạn thực hiện. Viết bình luận dài đẹp cho tất cả các chức năng quan trọng và nhỏ hơn cho các chức năng khác. Mô tả rõ ràng giao diện của bạn, từng đối số, những gì nó làm và những gì nó trả về. Đây là rất nhiều công việc làm thêm, nhưng sẽ vô cùng hữu ích cho cả bạn và những người khác. Nếu bạn có bất kỳ chức năng nào có thể không hoạt động trên các bảng khác nhau, hãy đề cập đến nó ở đây. Nếu đây là các chức năng trung gian đang được sử dụng bởi các chức năng khác và có thể cần thiết, hãy đề cập trong Readme.
Đảm bảo mọi thứ, ngay cả các bình luận, đều nhất quán trên các tệp .hvà .cpp.
Chỉ giữ các chức năng liên quan trong một tệp duy nhất. Có một vài mô-đun nhỏ, nhưng nhất quán về mặt logic, tốt hơn một tệp lớn với mọi thứ trong đó.
Viết một tệp readme rõ ràng mô tả thư viện, khả năng của nó, bất kỳ vấn đề hoặc lỗi và khả năng sử dụng cơ bản. Sử dụng một tệp riêng để xác định và giải thích từng giao diện như được mô tả ở trên.
Một khi thư viện trở nên lớn, việc chia nó thành các thư mục có thể cần thiết. Điều này là không dễ dàng trong khi sử dụng arduino-ide . Nhưng, nếu bạn đạt đến mức này, có lẽ bạn là người dùng Arduino tiên tiến và sử dụng các công cụ phát triển mạnh mẽ hơn. Nếu không, đây là vũ trụ bảo bạn làm như vậy.
Hãy chắc chắn để thêm một giấy phép.
Sử dụng công cụ VCS như Git hoặc SVN. Điều này sẽ giúp dễ dàng hơn để xem các thay đổi được thực hiện, trở lại các phiên bản cũ, phát hiện lỗi gây ra lỗi và thậm chí cộng tác với những người khác.
Câu trả lời của AshRj rất hay - tôi chỉ có 2 điểm để thêm vào.
Điểm 1: Tài liệu
AshRj đề nghị viết một readme chi tiết. Trong khi điều này có thể là thực tiễn tốt, nó có thể nhanh chóng vượt khỏi tầm tay với các thư viện lớn hơn - thực sự, thậm chí ở một vài nghìn dòng (thực sự không nhiều), một readme sẽ gần như không có lợi ích. Đề nghị của tôi sẽ là tiến thêm một bước và sử dụng tương đương với Javadocs cho C ++ - vì câu trả lời này giải thích (đó là trên Stack Overflow), Doxygen là một công cụ rất hữu ích để giữ tài liệu có thể quản lý và xử lý (không ai muốn chỉnh sửa Tập tin readme dòng 10K ...)
Điểm 2: Thư mục
Một lần nữa tương phản với câu trả lời của AshRj, luôn luôn sử dụng các thư mục. Ngay cả khi bạn chỉ có 10 tệp, thậm chí chỉ với 7 hoặc 8. Tôi biết nó nghe có vẻ hơi ngu ngốc, nhưng nó sẽ chứng minh công việc của bạn trong tương lai và nếu bạn không bắt đầu sớm, bạn sẽ kết thúc với một mớ hỗn độn các tập tin. Các thư mục không chỉ dành cho các dự án lớn - những dự án nhỏ cũng nên sử dụng chúng. Chỉ cần nhớ rằng trong C ++ (ngôn ngữ Arduino thực tế), các thư mục bị bỏ qua khi bao gồm các tệp từ thư viện - chúng chỉ tồn tại như một công cụ quản lý mã.