Belgeleme yerine örnekleri tercih edin. Davranışsal bir problem mi?

Ne zaman yeni bir API veya programlama dili veya hatta basit Linux kılavuz sayfaları ile karşılaştığım zaman, her zaman (hatırladığımdan beri) onlardan kaçındım ve bunun yerine tembel olarak yeni kavramları anlama kazanma örneklerine güvendim.

Bilinçaltında, basit veya şifreli olmadığı veya sadece düz sıkıcı olduğu zaman belgelerden / API'lerden kaçınırım. Programlamaya başladığımdan bu yana yıllar geçti ve şimdi artık resmi olarak verdiğim örneklerden milyonlarca kat daha iyi olduğundan şifreli / zor belgeleri okumaktan kaçınmaktan daha fazla zarara neden olduğumu fark ettiğimi anladım. dokümantasyon, oradaki herhangi bir örnekten daha fazla kapsamı vardır Bu örneklerin öğrenmeye yönelik “birincil” kaynak yerine “katma” değer olarak ele alınması gerektiğini fark ettikten sonra bile.

Bu kötü alışkanlığı programcı olarak nasıl kırabilirim ya da çok mu düşüyorum?

Örneklerin tercihine güvenme alışkanlığı yanlış bir şey değildir: sizin için, cevabınızı almanın en hızlı yolu budur. Üstelik örnekler görsel. Metin paragraflarını okumak yerine, görsel olarak ayrıştırmak ve ihtiyacınız olan bilgiyi çıkarmak daha kolaydır.

Örnek:

Ürünleri listelemek için , buradaki tek fiil olduğundan dolayı Index, Productskontrolörün eylemini kullanmalısınız GET(ürünleri veritabanında üretmek, değiştirmek ve silmek için kullanılan eylemler hakkında daha fazla bilgi için, bkz. [Ürünleri etkileme]).

Belirli bir ürün hakkında ayrıntılı bilgi edinmek için, benzersiz tanımlayıcısını URI'nin sonuna ekleyin. Kullanılabilir her ürünün listesini almak istiyorsanız, hiçbir şey eklemeyin. Filtreleri, kılavuzun [Verileri seçmek için REST filtreleri] bölümünde açıklanan şekilde kullanabilirsiniz. Ürün listesinin bin öğe ile sınırlı olduğunu unutmayın. [Sayfalandırma], her sayfanın hala bin öğe ile sınırlı olması koşuluyla listenin tamamında gezinmek için kullanılabilir.

Ayrıca, servisi stoktaki miktarları yenilemeye zorlamak isteyebilirsiniz. Bu bir ayarlayarak yapılır refresh-quantities.

ayrıntılı, ancak sıkıcı ve zar zor okunabilir. Bağlantıları takip etmeniz gerektiği gerçeği işleri daha da kötüleştirir. Bazı örnekler eklersek, anlaşılması daha kolay olur:

GET Ürünleri / Endeks /
GET Ürünleri / Endeks / 12345 /
GET Ürünleri / Endeks /? Atla = 100 & al = 20
GET Ürünleri / Endeks /? Kategorisi = 12
GET Ürünleri / Endeks /? Fiyat = 0..39.90
GET Ürünleri / Endeks /? kategori = 12 & = 100 atlamak & almak = 20

Sadece örnekleri kullanmanız bir sorun olabilir. Örnekleri kullanmayı kesin olarak bırakmayın, ancak fikri bir kez öğrendiğinizde daha ayrıntılı bir belgenin yardımcı olabileceğini unutmayın. Örneğin, yukarıdaki örnek, ürün listesinin 1 000 ile sınırlı olduğunu göstermez: bunun için belgeleri okumanız gerekir.

Belgeleri okuman gerektiğini ne zaman biliyorsun?

API veya kitaplık her zaman beklediğiniz gibi davranmıyor. Örneğin, örneği alın ve şunları yapın:

GET Ürünleri / Endeks /? Atla = 6000 ve al = 3000

Bazı sebeplerden dolayı, veritabanında yirmi binin üzerinde ürün varken, 3.000'den az öğe döndürür. Burada, API gibi davranmıyor sen beklendiği, bu nedenle ayrıntılı belgeler okumak için iyi bir zaman.

Belgelerle sağlanan bilgiler üç kategoriye ayrılır:

• Yemek tarifi.
• Referans.
• Uzman bilgisi.

Tarifler veya örnek, sorun alanı ile yazılımın işlevleri arasında bir köprü oluşturur. Referans tamamen bazı işlevler tanımlamaktadır ve bir tarifi belirli bir duruma uyarlamak istiyorsanız kullanışlıdır.

(Uzman bilgisi, sorunlu alanın kavramlarını dokümantasyon kavramlarıyla eşleştirir, kavramların birkaç şekilde ifade edilip edilmeyeceği veya yazılım kullanıcılarının alanda uzman olmadığı durumlarda faydalıdır.)

Bu kötü alışkanlığı programcı olarak nasıl kırabilirim veya fazla düşünebilir miyim? Diğer programcılardan gelen herhangi bir bilgelik takdir edilmektedir.

Alışkanlığının kötü olduğunu sanmıyorum. Bir API öğrendiğinizde, ilk önce Tarifler yardımı ile hangi problemlerin çözülebileceği ve hangi metodolojilerin sağlanabileceği hakkında bir fikir edinebilirsiniz. Referans belgeler daha sonra metodolojileri özel durumlara göre ayarlamanıza yardımcı olur.

Örnekler dökümantasyondur. API bakış açısına aşina olmanın kötü olduğunu düşünmüyorum. Baktığınız tek belge buysa, sorun olabilir. Çoğu örnek, hata belgelerini geri alır ve eksik parçaları referans belgelerinden alırsanız aşırı kırılgan koda neden olabilir.

Farklı insanlar farklı şekillerde daha iyi öğrenirler. Bazı insanlar senin gibiler ve örneklerden daha iyi öğreniyorlar. Bazı insanlar benim gibi ve ayrıntılı belgelerden daha iyi öğreniyorlar. Her ikisinde de dokümantasyona sahip olmak çoğu geliştiriciyi oldukça iyi karşılamaktadır. Bir öğretmenle konuşun, size insanların öğrendiği yarım düzine yolu söyleyebilirler.