Apa prinsip inti yang Anda inginkan di perpustakaan?

Ada berbicara tentang apa sintaks dan fitur yang Anda sukai dalam bahasa pemrograman; sekarang saya akan bertanya prinsip atau fitur inti apa yang Anda inginkan di perpustakaan dalam bahasa favorit Anda (atau apa pun)?

Contohnya adalah menambahkan daftar + = anotherList valid sebagai lawan hanya mengizinkan daftar + = listElement (walaupun beberapa orang mungkin menganggap ini sebagai ide yang buruk)

Saya akan mengikuti praktik terbaik yang dapat Anda temukan di Cara mendesain API yang baik dan mengapa itu penting oleh Joshua Blosh (Google) . Versi PDF dapat ditemukan di sini .

Menurutnya, karakteristik API yang baik adalah:

Mudah dipelajari
mudah untuk digunakan, bahkan tanpa dokumentasi
Sulit untuk menyalahgunakan
mudah dibaca dan memelihara kode yang menggunakan itu
Cukup kuat untuk memenuhi kebutuhan
mudah untuk memperpanjang
tepat untuk audiens

Saya ingin yang berikut ini:

• Ruang nama yang didefinisikan dengan jelas. Karena C adalah bahasa utama saya, saya juga ingin makro cocok dengan ini. Menyelesaikan konflik di daerah itu menyebalkan.

• Jika Anda mengalokasikan sesuatu, beri saya petunjuk yang jelas bahwa itu harus dibebaskan. Ini masuk ke poin saya berikutnya, yaitu dokumentasi.

• Dokumentasikan perpustakaan. Alat-alat seperti Doxygen sederhana dan portabel, tidak ada alasan untuk tidak memberi saya sesuatu yang dapat saya hasilkan dan jelajahi.

• Jenis dokumen buram di header publik. Aku akan tetap menemukan mereka, katakan padaku mengapa kamu tidak ingin aku mengacaukan mereka dan apa yang bisa terjadi jika aku melakukannya. Jika Anda benar-benar menginginkan tambalan, saya perlu tahu apa yang Anda pikirkan.

• Jangan jatuh dan lari. Saya sangat menghargai komentar seperti "Tolong, jangan hubungi saya tentang ini. Saya tidak punya niat untuk mempertahankannya. Ini memecahkan masalah langsung saya, mungkin itu akan menyelesaikan masalah Anda. Saya tidak peduli, saya tidak akan memperbarui ini dan Anda dapat merasa bebas untuk membayarnya. " Saya tidak bisa memberi tahu Anda berapa banyak waktu yang menyelamatkan saya.

• Seharusnya tidak ada kebocoran memori atau kesalahan pada kode yang ada. Jika Anda tidak menguji sebelum mendorong barang ke kode Anda sendiri, mengapa Anda tergoda untuk mendorongnya ke saya?

• Jika memang perpustakaan, gunakan lisensi yang permisif dan konsisten. Jangan putuskan tiga bulan dari sekarang bahwa Anda seharusnya menghasilkan lebih banyak uang darinya. Itu sangat mengganggu malam sebelum Anda mengirimkan sesuatu dan menyadari bahwa Anda harus menulis ulang banyak kode perpustakaan karena lisensi berubah. Persis seperti itulah yang membuat saya cukup jengkel untuk mengimplementasikan kembali barang-barang Anda di bawah lisensi MIT.

• Konsisten dalam gaya pengkodean, orang lain harus membaca kode Anda untuk mengetahui apa yang sebenarnya dilakukan ketika hal-hal tidak berfungsi seperti yang diharapkan.

• Jangan gunakan lebih dari 110 kolom, kode Anda mungkin harus diedit, dan saya mungkin hanya memiliki tampilan 80x25. Jika Anda mengandalkan tab untuk membuat hal-hal terlihat lebih 'elegan', Anda memiliki masalah lain untuk dipecahkan.

• Cobalah untuk setidaknya mempertimbangkan port, jika tidak berurusan dengan bahasa yang ditafsirkan. Meskipun begitu, cobalah untuk setidaknya mempertimbangkan port.

• Beri aku tes. Saya harap Anda memilikinya, saya mungkin menyarankan mereka sebaliknya dan saya mungkin benar-benar membantu menulisnya berdasarkan grafik panggilan. Jika saya mengalami semua masalah itu, silakan gunakan . Jika tidak, Anda mendapatkan tambalan yang "berfungsi untuk saya !!!" :)

• Jangan merusak API, titik. Saya tahu Anda mungkin menyadari bahwa Anda salah menjalankan semua itu, tetapi pastikan hal-hal yang tertaut ke Anda tidak akan terputus pada pembaruan sederhana. Itu mungkin berarti beberapa cruft dan kludges, selamat datang di dunia perpustakaan.

• Berikan saya peta jalan sehingga saya tidak menduplikasi pekerjaan Anda, atau pekerjaan orang lain.

Saya mungkin akan mengedit posting ini untuk menambahkan lebih banyak.

Saya lebih peduli tentang fitur lunak API. Itu adalah:

• Kesederhanaan
• Konsistensi
• Keanggunan
• Intuitif
• Itu hanya bekerja

Saya bisa memperbaiki buku tentang bagaimana hal itu berlaku atau akan diterapkan, tetapi cukup untuk mengatakan kecuali jika pengguna API dapat membungkus kepala mereka di sekitar cara menggunakannya secara efektif, itu penggunaan terbatas. Kesederhanaan tidak berarti kesederhanaan, sama seperti keanggunan tidak berarti hidup. Ini hanya berarti bahwa itu sempurna untuk pekerjaan itu. Semakin sedikit seseorang harus berpikir tentang cara menggunakan API, semakin mereka bisa menggunakannya.

Bagaimana tampilan ini tergantung pada lnaguage, tujuan, dan target audiens API. Kriteria terakhir bermuara pada prinsip paling tidak mengejutkan. Tidak ada kesalahan di mana Anda tidak mengharapkannya. Setiap interpretasi yang masuk akal dari API akan memberi Anda hasil yang Anda inginkan.

Jadikan Hal-Hal Sederhana Menjadi Hal-Hal Sederhana dan Rumit

Ini cukup meringkas setiap filosofi desain lainnya. Jika perpustakaan Anda hanya membuat hal-hal rumit menjadi mungkin, orang-orang yang ingin menyelesaikan 80% kasus penggunaan termudah akan tergoda untuk menemukan kembali roda daripada berurusan dengan keburukan rekayasa berlebihan Anda yang mengharuskan Anda untuk menggunakan 6 kelas berbeda untuk melakukan hal yang setara dengan perpustakaan Anda dengan "Halo" Dunia".

Jika perpustakaan Anda hanya membuat hal-hal sederhana menjadi sederhana, orang-orang akan menjadi jengkel dengan sangat cepat ketika mereka mengetahui bahwa mereka perlu menulis ulang kode mereka hanya karena mereka memiliki persyaratan yang sedikit keluar jalur.

Cara terbaik untuk mencapai ini adalah:

• Jadilah liberal dalam apa yang Anda terima. Jika Anda memprogram dalam bahasa yang dinamis, gunakan pengetikan bebek untuk efek penuh. Jika Anda memprogram dalam C ++ atau D, gunakan templat sedapat mungkin. Terima apa pun yang memuaskan beberapa antarmuka struktural yang cukup universal. Jangan memaksa pengguna Anda untuk melakukan banyak pekerjaan yang sibuk mengubah data dari satu format ke format lainnya.

• Bangun fungsionalitas kenyamanan tingkat tinggi ke dalam pustaka Anda, tetapi bangun secara transparan di atas fungsionalitas level bawah, dan pastikan fungsionalitas level bawah ada untuk orang yang membutuhkannya.

• Ikuti prinsip kejutan paling tidak secara default, bahkan ketika melakukannya dapat membatasi fleksibilitas atau efisiensi. Jika perlu, tambahkan fungsi kedua dengan nama yang lebih verbose yang menekankan keterkejutannya untuk memungkinkan optimasi atau peningkatan fleksibilitas.

• Enkapsulasi bermanfaat, tetapi jangan anal tentang hal itu. Orang-orang dengan persyaratan yang tidak biasa dan tidak terduga kadang-kadang mungkin perlu mendapatkan di bawah salah satu abstraksi Anda untuk menyelesaikan pekerjaan. Di sisi lain, akan sulit untuk menembak diri sendiri secara tidak sengaja, ketika menggunakan konstruksi yang tampaknya tidak bersalah . Ingatlah hal ini ketika memutuskan seberapa ketat Anda ingin mengunci barang-barang.

• Gunakan banyak contoh dalam dokumentasi Anda. Ini berfungsi untuk menggambarkan kasus penggunaan umum kepada pengguna Anda dan untuk memaksa Anda berpikir tentang apakah kasus yang paling umum cukup efisien.

• Memiliki default yang masuk akal untuk semua yang Anda bisa, tetapi pastikan default itu hanya default dan sudah jelas bagaimana menimpanya.

• Wajar, minimalis sehat

Itu saja. Bandingkan, sebagai contoh, mekanisme pipa pada Windows dan UNIX. Satu menawarkan banyak fungsi API khusus dengan sekelompok argumen yang tidak jelas, tidak perlu atau jarang digunakan, yang masing-masing dapat memiliki salah satu dari banyak nilai makro / konstan. UNIX pada dasarnya menggunakan kembali antarmuka terbuka / baca / tulis / tutup yang ada, ditambah beberapa metode yang sangat sederhana untuk beberapa kasus tertentu, seperti socketpair () atau pipe (). Benar-benar hampir, hampir tidak ada hal baru yang harus Anda pelajari untuk menggunakan pipa di UNIX. Sekarang bandingkan dengan ini .

(Agar adil, Microsoft awalnya hanya "meminjam" antarmuka dari OS / 2 IBM.)