ต้องการตัวอย่างมากกว่าเอกสาร มันเป็นปัญหาพฤติกรรมหรือไม่?

เมื่อใดก็ตามที่ฉันเจอAPIใหม่หรือภาษาการเขียนโปรแกรมหรือแม้แต่หน้าลินุกซ์อย่างง่ายฉันมักจะหลีกเลี่ยงพวกเขา (นับตั้งแต่ที่ฉันจำได้) และมักจะพึ่งพาตัวอย่างเพื่อทำความเข้าใจแนวคิดใหม่ ๆ

โดยไม่รู้ตัวฉันจะหลีกเลี่ยงเอกสาร / API ทุกครั้งที่มันไม่ตรงไปตรงมาหรือเป็นความลับหรือน่าเบื่อเพียงธรรมดา เป็นเวลาหลายปีแล้วที่ฉันเริ่มเขียนโปรแกรมและตอนนี้ฉันรู้สึกว่าฉันต้องแก้ไขวิธีการของฉันเมื่อฉันรู้ว่าฉันสร้างความเสียหายมากขึ้นโดยการละเว้นจากการอ่านเอกสารที่เป็นความลับ / ยากเนื่องจากยังดีกว่าตัวอย่างเป็นทางการ เอกสารมีความครอบคลุมมากกว่าตัวอย่างจากที่นั่น แม้หลังจากตระหนักว่าตัวอย่างควรได้รับการปฏิบัติเหมือนเป็นค่า "เพิ่ม" แทนที่จะเป็นแหล่ง "หลัก" สำหรับการเรียนรู้

ฉันจะทำลายนิสัยที่ไม่ดีนี้ในฐานะโปรแกรมเมอร์หรือฉันคิดมากได้อย่างไร

นิสัยของการพึ่งพาความชอบในตัวอย่างนั้นไม่มีอะไรผิดปกติสำหรับคุณมันเป็นวิธีที่เร็วที่สุดในการรับคำตอบของคุณ ยิ่งกว่านั้นภาพตัวอย่างก็เป็นภาพ มันง่ายกว่าที่จะแยกวิเคราะห์ตัวอย่างที่มองเห็นได้มากกว่าอ่านย่อหน้าของข้อความและดึงข้อมูลที่คุณต้องการ

ตัวอย่าง:

ในการแสดงรายการผลิตภัณฑ์เราควรใช้IndexการกระทำของProductsคอนโทรลเลอร์เนื่องจากGETเป็นกริยาเดียวที่เป็นไปได้ที่นี่ (ดู [ผลิตภัณฑ์ที่ได้รับผลกระทบ] สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการกระทำที่ใช้ในการสร้างแก้ไขและลบผลิตภัณฑ์ออกจากฐานข้อมูล)

ในการรับข้อมูลรายละเอียดเกี่ยวกับผลิตภัณฑ์เฉพาะให้เพิ่มตัวระบุเฉพาะต่อท้าย URI หากคุณต้องการได้รับรายชื่อของทุกผลิตภัณฑ์ที่มีอยู่ไม่ผนวกอะไร คุณสามารถใช้ตัวกรองตามที่อธิบายไว้ในส่วน [ตัวกรอง REST สำหรับการเลือกข้อมูล] ของคู่มือ โปรดทราบว่ารายการผลิตภัณฑ์ถูก จำกัด ไว้ที่หนึ่งพันรายการ [การแบ่งหน้า] สามารถใช้ในการเดินผ่านรายการทั้งหมดเนื่องจากแต่ละหน้ายัง จำกัด อยู่เพียงหนึ่งพันรายการ

คุณอาจต้องการบังคับให้บริการรีเฟรชปริมาณในสต็อก สิ่งนี้ทำได้โดยการตั้งค่าเป็นrefresh-quantitiesหนึ่ง

มีรายละเอียด แต่น่าเบื่อและแทบอ่านไม่ได้ ความจริงที่ว่าคุณต้องติดตามลิงค์ทำให้สิ่งต่าง ๆ แย่ลงไปอีก หากเราผนวกตัวอย่างบางส่วนมันจะง่ายต่อการเข้าใจมากขึ้น:

GET ผลิตภัณฑ์ / ดัชนี /
ผลิตภัณฑ์ GET / ดัชนี / 12345 /
GET ผลิตภัณฑ์ / ดัชนี /? skip = 100 & รับ = 20
GET ผลิตภัณฑ์ / ดัชนี / หมวดหมู่ = 12
GET ผลิตภัณฑ์ / ดัชนี / ราคา = 0..39.90
GET ผลิตภัณฑ์ / ดัชนี /? หมวดหมู่ = 12 & ข้าม = 100 และใช้เวลา = 20

ความจริงที่ว่าคุณใช้ตัวอย่างเท่านั้นอาจเป็นปัญหา อย่าหยุดใช้ตัวอย่าง แต่อย่าลืมว่าเมื่อคุณมีความคิดแล้วเอกสารประกอบที่ละเอียดมากขึ้นอาจช่วยได้ ตัวอย่างเช่นตัวอย่างข้างต้นไม่แสดงว่ารายการผลิตภัณฑ์นั้น จำกัด ไว้ที่ 1,000 รายการ: คุณต้องอ่านเอกสารประกอบสำหรับสิ่งนั้น

เมื่อไหร่ที่คุณรู้ว่าคุณควรอ่านเอกสาร?

ทุกครั้งที่ API หรือไลบรารีไม่ทำงานตามที่คาดไว้ ตัวอย่างเช่นคุณคว้าตัวอย่างและทำ:

รับผลิตภัณฑ์ / ดัชนี /? skip = 6000 และรับ = 3000

ด้วยเหตุผลบางอย่างมันส่งคืนสินค้าน้อยกว่า 3,000 รายการในขณะที่คุณมีผลิตภัณฑ์มากกว่าสองหมื่นรายการในฐานข้อมูลของคุณ ที่นี่ API ไม่ทำงานเหมือนที่คุณคาดไว้ดังนั้นจึงเป็นเวลาที่ดีในการอ่านเอกสารรายละเอียด

ข้อมูลที่จัดทำโดยเอกสารประกอบอยู่ในสามหมวดหมู่:

• สูตรอาหาร.
• การอ้างอิง
• ความรู้จากผู้เชี่ยวชาญ

สูตรหรือตัวอย่างทำให้สะพานเชื่อมระหว่างโดเมนปัญหากับฟังก์ชันการทำงานของซอฟต์แวร์ การอ้างอิงอธิบายถึงฟังก์ชันการทำงานบางอย่างโดยสมบูรณ์และมีประโยชน์หากคุณต้องการปรับสูตรให้เหมาะกับกรณีและปัญหา

(ความรู้ผู้เชี่ยวชาญแผนที่แนวคิดของโดเมนปัญหากับแนวคิดของเอกสารมันจะมีประโยชน์หากแนวคิดสามารถแสดงในหลายมารยาทหรือหากผู้ใช้ซอฟต์แวร์ไม่ใช่ผู้เชี่ยวชาญในสาขา)

ฉันจะทำลายนิสัยที่ไม่ดีนี้ในฐานะโปรแกรมเมอร์หรือฉันเกินความคิดได้อย่างไร ภูมิปัญญาจากโปรแกรมเมอร์เพื่อน ๆ ที่ชื่นชม

ฉันไม่คิดว่านิสัยของคุณไม่ดี เมื่อคุณเรียนรู้ API คุณจะได้รับความคิดว่าปัญหาใดที่สามารถแก้ไขได้และวิธีการใดที่ได้รับความช่วยเหลือจากตำรับอาหาร (ตัวอย่างของคุณ) เอกสารอ้างอิงจะช่วยให้คุณปรับวิธีการในกรณีพิเศษ

ตัวอย่างเอกสาร ฉันไม่คิดว่ามันจะแย่สำหรับการทำความคุ้นเคยกับจุดยืนของ API หากเป็นเอกสารเพียงอย่างเดียวที่คุณดูอาจเป็นปัญหาได้ ตัวอย่างส่วนใหญ่อ่านการตรวจสอบข้อผิดพลาดซึ่งอาจนำไปสู่การโค้ดที่เปราะมากเกินไปหากคุณไม่ย้อนกลับไปรับชิ้นส่วนที่หายไปจากเอกสารอ้างอิง

ผู้คนต่างเรียนรู้ได้ดีขึ้นในวิธีที่ต่างกัน บางคนเป็นเหมือนคุณและเรียนรู้จากตัวอย่างได้ดีขึ้น บางคนเป็นเหมือนฉันและเรียนรู้ที่ดีขึ้นจากเอกสารรายละเอียด การมีทั้งในเอกสารประกอบดูเหมือนว่าจะครอบคลุมนักพัฒนาส่วนใหญ่ค่อนข้างดี พูดคุยกับครูพวกเขาสามารถบอกคุณครึ่งโหลวิธีที่ผู้คนเรียนรู้