Lebih suka contoh daripada dokumentasi. Apakah ini masalah perilaku?

Setiap kali saya menemukan API atau bahasa pemrograman baru atau bahkan halaman manual Linux yang sederhana , saya selalu (sejak saya ingat) menghindarinya dan sebaliknya dengan malas mengandalkan contoh untuk mendapatkan pemahaman konsep baru.

Secara tidak sadar, saya menghindari dokumentasi / API setiap kali tidak langsung atau samar atau hanya membosankan. Sudah bertahun-tahun sejak saya mulai pemrograman dan sekarang saya merasa perlu memperbaiki cara saya karena sekarang saya menyadari bahwa saya menyebabkan lebih banyak kerusakan dengan menahan diri dari membaca dokumentasi samar / sulit karena masih sejuta kali lebih baik daripada contoh sebagai pejabat dokumentasi memiliki cakupan lebih dari contoh apa pun di luar sana. Bahkan setelah menyadari bahwa contoh-contoh harus diperlakukan sebagai nilai "tambah" alih-alih sumber "primer" untuk belajar.

Bagaimana saya menghentikan kebiasaan buruk ini sebagai seorang programmer atau saya terlalu banyak berpikir?

Kebiasaan mengandalkan preferensi pada contoh tidak ada yang salah: bagi Anda, itu hanya cara tercepat untuk mendapatkan jawaban Anda. Apalagi contohnya visual. Lebih mudah untuk mem-parsing secara visual contoh daripada membaca paragraf teks dan mengekstrak informasi yang Anda butuhkan.

Contoh:

Untuk membuat daftar produk, seseorang harus menggunakan Indexaksi Productscontroller, mengingat itu GETadalah satu-satunya kata kerja yang mungkin di sini (lihat [Mempengaruhi produk] untuk informasi lebih lanjut tentang tindakan yang digunakan untuk membuat, memodifikasi, dan menghapus produk dari database).

Untuk mendapatkan informasi terperinci tentang produk tertentu, tambahkan pengenal uniknya ke akhir URI. Jika Anda ingin mendapatkan daftar setiap produk, jangan tambahkan apa pun. Anda juga dapat menggunakan filter, seperti yang dijelaskan di bagian [filter REST untuk memilih data] dari manual. Perhatikan bahwa daftar produk dibatasi hingga seribu item. [Pagination] dapat digunakan untuk menelusuri seluruh daftar, mengingat bahwa setiap halaman masih terbatas pada seribu item.

Anda mungkin juga ingin memaksa layanan untuk menyegarkan jumlah dalam stok. Ini dilakukan dengan mengatur refresh-quantitieske satu.

terperinci, tetapi membosankan dan sulit dibaca. Fakta bahwa Anda perlu mengikuti tautan membuat segalanya semakin buruk. Jika kami menambahkan beberapa sampel, menjadi lebih mudah dipahami:

DAPATKAN Produk / Indeks /
DAPATKAN Produk / Indeks / 12345 /
DAPATKAN Produk / Indeks /? Lewati = 100 & ambil = 20
DAPATKAN Produk / Indeks /? Kategori = 12
DAPATKAN Produk / Indeks /? Harga = 0..39.90
DAPATKAN Produk / Indeks /? kategori = 12 & lewati = 100 & ambil = 20

Fakta bahwa Anda hanya menggunakan contoh mungkin menjadi masalah. Jangan terus-menerus berhenti menggunakan contoh-contoh ini, tetapi ingatlah bahwa begitu Anda mendapatkan ide, dokumentasi yang lebih jelas dapat membantu. Misalnya, sampel di atas tidak menunjukkan bahwa daftar produk dibatasi hingga 1.000: Anda harus membaca dokumentasi untuk itu.

Kapan Anda tahu bahwa Anda harus membaca dokumentasinya?

Setiap kali API atau pustaka tidak berperilaku seperti yang Anda harapkan. Misalnya, Anda mengambil sampel dan melakukan:

DAPATKAN Produk / Indeks /? Lewati = 6000 & ambil = 3000

Untuk beberapa alasan, ia mengembalikan kurang dari 3.000 item, sementara Anda memiliki lebih dari dua puluh ribu produk di database Anda. Di sini, API tidak berlaku seperti yang Anda harapkan, jadi ini saat yang tepat untuk membaca dokumentasi terperinci.

Informasi yang disediakan oleh dokumentasi termasuk dalam tiga kategori:

• Resep.
• Referensi.
• Pengetahuan ahli.

Resep atau contoh membuat jembatan antara domain masalah dan fungsi perangkat lunak. Referensi menjelaskan sepenuhnya beberapa fungsi dan berguna jika Anda ingin mengadaptasi resep ke kasus tertentu.

(Pengetahuan ahli memetakan konsep domain masalah ke konsep dokumentasi, akan berguna jika konsep dapat diungkapkan dalam beberapa cara atau jika pengguna perangkat lunak bukan ahli di lapangan.)

Bagaimana saya menghentikan kebiasaan buruk ini sebagai seorang programmer atau saya terlalu berpikir? Setiap kebijaksanaan dari sesama programmer sangat dihargai.

Saya tidak berpikir bahwa kebiasaan Anda buruk. Saat Anda mempelajari suatu API, Anda pertama-tama mendapatkan gagasan tentang masalah mana yang dapat diselesaikan dan metodologi mana yang disediakan dengan bantuan Resep (contoh Anda). Dokumentasi referensi kemudian membantu Anda menyempurnakan metodologi untuk kasus-kasus khusus.

Contohnya adalah dokumentasi. Saya tidak berpikir itu buruk dari menjadi terbiasa dengan sudut pandang API. Jika itu adalah satu-satunya dokumentasi yang Anda lihat maka itu bisa menjadi masalah. Sebagian besar contoh berhemat pada pemeriksaan kesalahan yang dapat menyebabkan kode terlalu rapuh jika Anda tidak kembali dan mengambil bagian yang hilang dari dokumentasi referensi.

Orang yang berbeda belajar lebih baik dengan cara yang berbeda. Beberapa orang menyukai Anda dan belajar lebih baik dari contoh. Beberapa orang menyukai saya dan belajar lebih baik dari dokumentasi terperinci. Memiliki keduanya dalam dokumentasi tampaknya mencakup sebagian besar pengembang dengan cukup baik. Bicaralah dengan seorang guru, mereka dapat memberi tahu Anda setengah lusin cara orang belajar.