Saya sedang mengerjakan proyek Arduino menggunakan Uno. Proyek ini mengandung sejumlah besar kode. Saya ingin membuat perpustakaan dan saya bahkan dapat membaginya nanti. Pedoman apa yang harus saya ikuti saat mendesain perpustakaan?
Jawaban:
Ada banyak poin yang harus Anda ingat saat mendesain perpustakaan. Seperti yang mungkin Anda lakukan, pada akhirnya membagikan karya Anda dengan orang lain, sangat penting untuk mengikuti pola desain yang konsisten. Perlu diingat bahwa pengguna lain akan memiliki tingkat keterampilan yang sangat beragam, jadi rancang perpustakaan yang mudah digunakan, semaksimal mungkin.
Berikan peta pin dasar yang diharapkan oleh perpustakaan Anda. Jangan biarkan pemetaan pin statis tetapi memungkinkan pengguna untuk membuat perubahan dengan mudah.
Salah satu hal pertama yang harus Anda coba pastikan adalah perpustakaan Anda berfungsi. Jika tidak, jelaskan demikian. Anda tidak ingin menghabiskan waktu untuk bekerja dengan perangkat lunak yang rusak, jadi jangan biarkan orang lain melakukannya juga.
Sebutkan dengan sangat jelas papan mana yang dirancang untuk perpustakaan itu, di mana ia diuji, dan papan apa yang diharapkan berfungsi. Tentukan generasi (versi) dari setiap papan yang disebutkan di sini.
Hal berikutnya adalah Anda harus memiliki antarmuka yang jelas. Perpustakaan yang berfungsi dengan antarmuka yang berbelit-belit membuat frustrasi. Ini akan membantu Anda menggunakan perpustakaan nanti, dan akan membuat segalanya lebih mudah bagi pengguna lain. Ini harus menjadi salah satu aspek terpenting yang perlu diingat.
Apakah Anda mengikuti pendekatan top-down atau bottom-up, antarmuka harus selalu jelas dalam pikiran Anda. Dalam pendekatan bottom-up, ini mungkin dan akan sulit, tetapi tidak boleh diabaikan. Jika tidak, Anda akan berakhir dengan perpustakaan yang terlalu rumit yang mungkin tidak dapat digunakan.
Jika Anda memiliki fungsi yang menggunakan beberapa karakteristik papan khusus, pastikan untuk membuat fungsi-fungsi ini menonjol, sebutkan dalam readme dan juga di komentar.
Mungkin ada skenario di mana Anda mungkin harus menunggu dengan sibuk. Fungsi tersebut, tergantung pada logika program, dapat mencegah aliran kontrol normal sehingga menyebabkan masalah saat berada di tengah tugas penting. Coba gunakan interupsi atau algoritma lainnya, jika memungkinkan. Jika tidak, maka sebutkan dengan jelas tandai fungsi tersebut.
Pastikan untuk terus mengomentari setiap perubahan kecil dan besar yang Anda lakukan. Tulis komentar panjang yang bagus untuk semua fungsi kritis dan yang lebih kecil untuk yang lain. Jelaskan antarmuka Anda secara eksplisit, setiap argumen, apa fungsinya, dan apa yang dikembalikan. Ini adalah pekerjaan ekstra, tetapi akan sangat membantu bagi Anda dan orang lain. Jika Anda memiliki fungsi yang mungkin tidak berfungsi di papan yang berbeda, sebutkan di sini. Jika ini adalah fungsi antara yang sedang digunakan oleh fungsi lain dan mungkin diperlukan, sebutkan dalam Readme.
Pastikan semuanya, bahkan komentar, konsisten di seluruh file .hdan .cpp.
Simpan hanya fungsi terkait dalam satu file. Memiliki beberapa modul kecil, tetapi konsisten secara logis, lebih baik daripada satu file besar dengan semua yang ada di dalamnya.
Tulis file readme yang jelas menggambarkan perpustakaan, kemampuannya, masalah atau bug, dan kegunaan dasar. Gunakan file terpisah untuk mendefinisikan dan menjelaskan setiap antarmuka seperti dijelaskan di atas.
Setelah perpustakaan menjadi besar membaginya menjadi direktori mungkin diperlukan. Ini tidak mudah dilakukan saat menggunakan arduino-ide . Tetapi, jika Anda mencapai sejauh ini, Anda mungkin adalah pengguna Arduino yang maju dan menggunakan alat pengembangan yang lebih kuat. Jika tidak, ini adalah semesta yang menyuruh Anda melakukannya.
Pastikan untuk menambahkan lisensi.
Gunakan alat VCS seperti Git atau SVN. Ini akan membuatnya lebih mudah untuk melihat perubahan yang dibuat, kembali ke versi lama, kode penyebab kesalahan tempat, dan bahkan berkolaborasi dengan orang lain.
Jawaban AshRj sangat bagus - saya hanya punya 2 poin untuk ditambahkan.
Butir 1: Dokumentasi
AshRj merekomendasikan untuk menulis readme terperinci. Walaupun ini bisa menjadi praktik yang baik, ini dapat dengan cepat keluar dari kendali dengan perpustakaan yang lebih besar - bahkan, bahkan pada beberapa ribu baris (yang sebenarnya tidak banyak), readme hampir tidak memiliki manfaat. Rekomendasi saya adalah untuk melangkah lebih jauh dan menggunakan Javadocs yang setara untuk C ++ - karena jawaban ini menjelaskan (ada di Stack Overflow), Doxygen adalah alat yang sangat berguna untuk menjaga dokumentasi dapat dikelola dan ditangani (tidak ada yang ingin mengedit File readme baris 10K ...)
Butir 2: Direktori
Sekali lagi bertentangan dengan jawaban AshRj, selalu gunakan direktori. Bahkan jika Anda hanya memiliki 10 file, mungkin bahkan hanya dengan 7 atau 8. Saya tahu kedengarannya agak bodoh, tapi ini akan membuktikan pekerjaan Anda di masa depan, dan jika Anda tidak memulai lebih awal, Anda hanya akan berakhir dengan kekacauan file. Direktori tidak hanya untuk proyek besar - yang kecil juga harus menggunakannya. Hanya ingat bahwa dalam C ++ (bahasa Arduino de-facto), direktori diabaikan ketika menyertakan file dari perpustakaan - mereka ada sebagai alat manajemen kode saja.