Apa kesamaan API yang hebat? [Tutup]

Ada apa dengan API hebat yang membuatnya hebat? Saya pikir menganut mantra "lakukan satu hal dan lakukan dengan baik" adalah pertanda baik dan menjadi pemetaan yang baik ke domain masalah adalah penting, tetapi apa kesamaan yang dimiliki API hebat?

Anda harus berhati-hati untuk menghindari penambahan kosa kata baru hanya demi API Anda. API favorit saya menjelaskan banyak hal kepada saya dalam kosa kata yang sudah saya mengerti. Sejalan dengan itu:

Jangan menambahkan terlalu banyak abstraksi di atas apa yang Anda bangun. Tetap sederhana.

Saya sudah harus memikirkan sekitar setengah lusin lapisan abstraksi. Jangan membuat saya berpikir tentang lapisan tambahan. Jangan beri saya terlalu banyak hal baru untuk dipelajari yang tidak akan menambah nilai pada tujuan akhir saya. Misalnya, hindari menggunakan kelas file khusus Anda sendiri yang bekerja secara berbeda maka jenis file bahasa hanya karena Anda berpikir cara Anda lebih baik daripada cara yang diterima secara umum. Tetap dengan cara yang diterima secara umum, setidaknya di antarmuka Anda, menjadi lebih baik atau lebih buruk.

Tetap dengan ide-ide konkret

Sebagai contoh jangan mencoba untuk menyembunyikan fakta bahwa "model" bagian dari kerangka kerja MVC Anda adalah ujung depan untuk database. Manfaatkan kosa kata terkenal di sekitar "database". Saya tahu kunci asing apa. Saya tahu baris dan kolom apa. Bicaralah dengan saya dalam hal ini.

Jangan mencabut pengetahuan esensial

Mirip dengan bekerja dengan ide-ide konkret. Jangan sembunyikan fakta bahwa kita berurusan dengan file atau database atau baris dalam database. Saya tahu hal-hal ini. Jika saya berurusan dengan wadah, seperti Daftar, ada peluang bagus yang perlu saya ketahui kompleksitas algoritmik dari operasi umum. Anda dapat menyederhanakan banyak itu hanya dengan memberi tahu saya "daftar tertaut" atau "larik". Seperangkat ide besar tiba-tiba akan dibawa untuk menanggung apa yang Anda lakukan dan semuanya akan tiba-tiba masuk akal. Jangan membuat set ide Anda sendiri yang harus saya pelajari ketika saya sudah akan datang dengan set terminologi yang kaya dan berguna untuk diterapkan pada masalah.

Kurangi jumlah istilah yang saya butuhkan dalam kosakata saya

Jika saya menggunakan API Anda untuk membuka file gambar jenis apa pun, saya tidak perlu terlalu memikirkan pngs vs gifs vs jpgs. Anda akan melakukannya untuk saya. Ini kompetensi inti Anda, bukan milikku. Saya memiliki pemahaman yang kabur bahwa Anda memiliki sihir untuk melakukan ini untuk saya.

API yang bermanfaat memiliki yang berikut:

• Dokumentasi yang ringkas dan menyeluruh. Jika saya mencari cara mengimplementasikan tugas, saya dapat mengetahui apakah API memiliki kemampuan untuk melakukannya, dalam beberapa menit. Ini dicapai dengan singkatnya teks dan tata letak sumber daya. Dokumentasi menyediakan contoh tentang cara menggunakannya dan juga tidak membuat asumsi pada pembaca.
• Komunitas yang besar dan aktif. Saya terpana ketika menemukan forum, saluran IRC, milis, dll. Dengan peserta aktif yang bersedia membantu orang-orang baru. Saya mengerti bahwa ini biasanya merupakan kasus untuk proyek yang lebih besar, tetapi tetap, akan menjadi sesuatu yang diperjuangkan.
• Konsistensi. Ketika saya benar-benar menggunakan API, saya tidak ingin terkejut dengan cara apa pun ketika saya memanggil metode, atau menemukan metode yang Xsama sekali berbeda dari konvensi yang ditetapkan oleh sisa API.

API Hebat memiliki dokumentasi hebat.

• Lakukan satu hal dan lakukan dengan baik.
• Mudah digunakan, sulit disalahgunakan.
• Mudah diperpanjang.
• Didokumentasikan dengan baik.
• Gaya yang konsisten.

Pertanyaan ini dibahas dalam "Desain API Praktis: Pengakuan Arsitek Kerangka Java" oleh Jaroslav Tulach dari tim NetBeans.

Antarmuka berguna yang paling sederhana dan konvensi penamaan yang baik.