Thích các ví dụ hơn tài liệu. Nó có phải là một vấn đề hành vi?

Bất cứ khi nào tôi bắt gặp một API mới hoặc ngôn ngữ lập trình hoặc thậm chí các trang người dùng Linux đơn giản , tôi luôn luôn (kể từ khi tôi nhớ) tránh chúng và thay vào đó lười biếng dựa vào các ví dụ để hiểu các khái niệm mới.

Theo tiềm thức, tôi tránh các tài liệu / API bất cứ khi nào nó không đơn giản hoặc khó hiểu hoặc chỉ đơn giản là nhàm chán. Đã nhiều năm kể từ khi tôi bắt đầu lập trình và bây giờ tôi cảm thấy mình cần phải sửa đổi theo cách của mình vì bây giờ tôi nhận ra rằng tôi đang gây ra nhiều thiệt hại hơn bằng cách kiềm chế đọc tài liệu khó hiểu / khó hiểu vì nó vẫn tốt hơn hàng triệu lần so với các ví dụ như chính thức tài liệu có phạm vi bảo hiểm nhiều hơn bất kỳ ví dụ ngoài kia. Ngay cả sau khi nhận ra rằng các ví dụ nên được coi là giá trị "được thêm" thay vì nguồn "chính" để học.

Làm thế nào để tôi bỏ thói quen xấu này với tư cách là một lập trình viên hay tôi đang suy nghĩ quá mức?

Thói quen dựa vào sở thích trên các ví dụ không có gì sai: đối với bạn, đó chỉ là cách nhanh nhất để có câu trả lời của bạn. Hơn nữa, các ví dụ là trực quan. Dễ dàng phân tích trực quan một ví dụ hơn là đọc các đoạn văn bản và trích xuất thông tin bạn cần.

Thí dụ:

Để liệt kê các sản phẩm, người ta nên sử dụng Indexhành động của Productsbộ điều khiển, đó GETlà động từ duy nhất có thể có ở đây (xem [Ảnh hưởng đến sản phẩm] để biết thêm thông tin về các hành động được sử dụng để tạo, sửa đổi và xóa sản phẩm khỏi cơ sở dữ liệu).

Để có được thông tin chi tiết về một sản phẩm cụ thể, hãy thêm số nhận dạng duy nhất của nó vào cuối URI. Nếu bạn muốn có danh sách mọi sản phẩm có sẵn, đừng nối thêm bất cứ thứ gì. Bạn cũng có thể sử dụng các bộ lọc, như được mô tả trong phần [Bộ lọc REST để chọn dữ liệu] trong hướng dẫn. Lưu ý rằng danh sách các sản phẩm được giới hạn ở một nghìn mặt hàng. [Phân trang] có thể được sử dụng để duyệt qua toàn bộ danh sách, với điều kiện là mỗi trang vẫn bị giới hạn ở một nghìn mục.

Bạn cũng có thể muốn buộc dịch vụ làm mới số lượng trong kho. Điều này được thực hiện bằng cách đặt refresh-quantitiesthành một.

là chi tiết, nhưng nhàm chán và hầu như không thể đọc được. Thực tế là bạn cần phải theo liên kết làm cho mọi thứ thậm chí còn tồi tệ hơn. Nếu chúng ta chắp thêm một số mẫu, nó sẽ trở nên dễ hiểu hơn nhiều:

NHẬN Sản phẩm / Chỉ mục /
NHẬN Sản phẩm / Chỉ mục / 12345 /
NHẬN Sản phẩm / Chỉ mục /? Skip = 100 & Take = 20
GET Sản phẩm / Chỉ mục /? Thể loại = 12
NHẬN Sản phẩm / Chỉ mục /? Giá = 0,39,90
Sản phẩm / Chỉ mục /? loại = 12 và bỏ qua = 100 và mất = 20

Việc bạn chỉ sử dụng các ví dụ có thể là một vấn đề. Đừng đơn giản ngừng sử dụng các ví dụ, nhưng hãy nhớ rằng một khi bạn có ý tưởng, một tài liệu dài dòng hơn có thể giúp ích. Ví dụ, mẫu ở trên không cho thấy rằng danh sách các sản phẩm bị giới hạn ở mức 1 000: bạn phải đọc tài liệu cho điều đó.

Khi nào bạn biết rằng bạn nên đọc tài liệu?

Mỗi khi API hoặc thư viện không hoạt động như bạn mong đợi. Ví dụ: bạn lấy mẫu và làm:

NHẬN Sản phẩm / Chỉ mục /? Bỏ qua = 6000 và lấy = 3000

Vì một số lý do, nó trả về ít hơn 3 000 mặt hàng, trong khi bạn có hơn hai mươi nghìn sản phẩm trong cơ sở dữ liệu của mình. Ở đây, API không hoạt động như bạn mong đợi, vì vậy đây là thời điểm tốt để đọc tài liệu chi tiết.

Thông tin được cung cấp bởi tài liệu rơi vào ba catgeories:

• Công thức.
• Tài liệu tham khảo.
• Kiến thức chuyên môn.

Bí quyết hoặc ví dụ làm cầu nối giữa miền vấn đề và các chức năng của phần mềm. Tham chiếu mô tả hoàn toàn một số chức năng và hữu ích nếu bạn muốn điều chỉnh một công thức cho một trường hợp cụ thể.

(Kiến thức chuyên môn ánh xạ các khái niệm của miền vấn đề thành các khái niệm về tài liệu, sẽ hữu ích nếu các khái niệm có thể được thể hiện theo một số cách hoặc nếu người dùng phần mềm không phải là chuyên gia trong lĩnh vực này.)

Làm thế nào để tôi bỏ thói quen xấu này với tư cách là một lập trình viên hay tôi đang suy nghĩ quá mức? Bất kỳ sự khôn ngoan từ các lập trình viên đồng nghiệp được đánh giá cao.

Tôi không nghĩ rằng thói quen của bạn là xấu. Khi bạn tìm hiểu API, trước tiên bạn sẽ biết được vấn đề nào có thể được giải quyết và phương pháp nào được cung cấp với sự trợ giúp của Bí quyết (ví dụ của bạn). Tài liệu tham khảo sau đó giúp bạn tinh chỉnh các phương pháp luận cho các trường hợp đặc biệt.

Ví dụ là tài liệu. Tôi không nghĩ nó tệ khi làm quen với quan điểm API. Nếu nó là tài liệu duy nhất mà bạn nhìn vào thì nó có thể là một vấn đề. Hầu hết các ví dụ tiết kiệm kiểm tra lỗi có thể dẫn đến mã quá dễ vỡ nếu bạn không quay lại và nhặt các phần còn thiếu từ tài liệu tham khảo.

Những người khác nhau học tốt hơn theo những cách khác nhau. Một số người giống bạn và học tốt hơn từ các ví dụ. Một số người giống tôi và học tốt hơn từ tài liệu chi tiết. Có cả hai trong tài liệu dường như bao gồm hầu hết các nhà phát triển khá tốt. Nói chuyện với một giáo viên, họ có thể cho bạn biết một nửa tá cách mọi người học.