API tuyệt vời có điểm gì chung? [đóng cửa]

Điều gì về API tuyệt vời làm cho chúng tuyệt vời? Tôi nghĩ rằng việc tuân thủ câu thần chú "làm một việc và làm tốt" là một dấu hiệu tốt và việc ánh xạ tốt đến miền vấn đề là rất quan trọng, nhưng API tuyệt vời có điểm gì chung?

Bạn phải cẩn thận để tránh thêm từ vựng mới chỉ vì lợi ích của API. API yêu thích của tôi giải thích mọi thứ cho tôi bằng từ vựng tôi đã hiểu. Dọc theo những dòng đó:

Đừng thêm quá nhiều trừu tượng lên trên những gì bạn đang xây dựng. Giữ cho nó đơn giản.

Tôi đã phải suy nghĩ về khoảng nửa tá lớp trừu tượng. Đừng làm tôi suy nghĩ về các lớp thêm. Đừng cho tôi quá nhiều điều mới để học mà sẽ không thêm giá trị cho mục tiêu cuối cùng của tôi. Ví dụ: tránh sử dụng lớp tệp đặc biệt của riêng bạn hoạt động khác với loại tệp của ngôn ngữ chỉ khiến bạn nghĩ rằng cách của bạn tốt hơn cách thường được chấp nhận. Hãy gắn bó với cách thức được chấp nhận chung, ít nhất là trong các giao diện của bạn, tốt hơn hoặc tồi tệ hơn.

Gắn bó với những ý tưởng cụ thể

Ví dụ: đừng cố che giấu sự thật rằng phần "mô hình" trong khung MVC của bạn là phần đầu cho cơ sở dữ liệu. Tận dụng các từ vựng nổi tiếng xung quanh "cơ sở dữ liệu". Tôi biết chìa khóa nước ngoài là gì. Tôi biết những hàng và cột là gì. Nói chuyện với tôi trong những điều khoản.

Đừng trừu tượng hóa những kiến ​​thức thiết yếu

Tương tự như làm việc với những ý tưởng cụ thể. Đừng che giấu sự thật rằng chúng ta đang xử lý các tệp hoặc cơ sở dữ liệu hoặc hàng trong cơ sở dữ liệu. Tôi biết những điều này. Nếu tôi đang xử lý một container, như Danh sách, rất có thể tôi cần biết độ phức tạp thuật toán của các hoạt động chung. Bạn có thể đơn giản hóa điều đó bằng cách chỉ cho tôi biết "danh sách được liên kết" hoặc "mảng". Một bộ ý tưởng khổng lồ sẽ đột nhiên được đưa ra để làm theo những gì bạn đang làm và tất cả sẽ đột nhiên có ý nghĩa. Đừng tạo ra bộ ý tưởng của riêng bạn mà tôi phải học khi tôi đã đi kèm với một bộ thuật ngữ phong phú và hữu ích để áp dụng cho vấn đề.

Giảm số lượng thuật ngữ tôi cần trong vốn từ vựng của tôi

Nếu tôi đang sử dụng API của bạn để mở tệp hình ảnh thuộc bất kỳ loại nào, tôi không cần phải suy nghĩ nhiều về pngs vs gifs vs jpgs. Bạn sẽ làm điều đó cho tôi. Đó là năng lực cốt lõi của bạn, không phải của tôi. Tôi có một số hiểu biết mơ hồ rằng bạn có một số phép thuật để làm điều này cho tôi.

Một API hữu ích có các mục sau:

• Tài liệu ngắn gọn và kỹ lưỡng. Nếu tôi đang tìm cách triển khai một nhiệm vụ, tôi có thể tìm hiểu xem API có khả năng thực hiện hay không, trong vài phút. Điều này đạt được bằng sự ngắn gọn của văn bản và bố cục của tài nguyên. Tài liệu này cung cấp các ví dụ về cách sử dụng nó và cũng không đưa ra giả định nào về độc giả.
• Một cộng đồng lớn, tích cực. Tôi bị thu hút khi tôi tìm thấy các diễn đàn, kênh IRC, danh sách gửi thư, v.v ... với những người tham gia tích cực sẵn sàng giúp đỡ những người mới. Tôi hiểu rằng đây thường là trường hợp cho các dự án lớn hơn, nhưng vẫn sẽ là một cái gì đó để phấn đấu.
• Tính nhất quán. Khi tôi thực sự sử dụng API, tôi không muốn bị sốc theo bất kỳ cách nào khi tôi gọi một phương thức hoặc phát hiện ra phương thức đó Xhoàn toàn khác với quy ước được đặt ra bởi phần còn lại của API.

API tuyệt vời có tài liệu tuyệt vời.

• Làm một điều và làm nó tuyệt vời.
• Dễ sử dụng, khó sử dụng.
• Dễ dàng mở rộng.
• Tài liệu tốt.
• Phong cách nhất quán.

Câu hỏi này được giải quyết trong "Thiết kế API thực tế: Lời thú tội của kiến ​​trúc sư khung Java" của Jaroslav Tulach từ nhóm NetBeans.

Giao diện hữu ích đơn giản nhất và quy ước đặt tên tốt.