Những nguyên tắc cốt lõi nào bạn muốn trong một thư viện?

Có nói về cú pháp và tính năng bạn thích trong ngôn ngữ lập trình; Bây giờ tôi sẽ hỏi những nguyên tắc hoặc tính năng cốt lõi nào bạn muốn có trong thư viện bằng ngôn ngữ yêu thích (hoặc bất kỳ) nào?

Một ví dụ có thêm danh sách + = otherList hợp lệ thay vì chỉ cho phép list + = listEuity (mặc dù một số có thể xem đây là một ý tưởng tồi)

Tôi sẽ làm theo các thực tiễn tốt nhất bạn có thể tìm thấy trong Cách thiết kế API tốt và lý do tại sao nó quan trọng bởi Joshua Blosh (Google) . Phiên bản PDF có thể được tìm thấy ở đây .

Theo ông, đặc điểm của một API tốt là:

Dễ học
Dễ sử dụng, thậm chí không cần tài liệu Dễ
sử dụng sai
Dễ đọc và duy trì mã sử dụng nó
Đủ mạnh mẽ để đáp ứng yêu cầu
Dễ dàng mở rộng
Phù hợp với đối tượng

Tôi muốn như sau:

• Một không gian tên được xác định rõ ràng. Vì C là ngôn ngữ chính của tôi, tôi cũng muốn các macro khớp với ngôn ngữ này. Giải quyết xung đột trong khu vực đó hút.

• Nếu bạn phân bổ một cái gì đó, hãy cho tôi một manh mối rõ ràng rằng nó phải được giải phóng. Điều này đi đến điểm tiếp theo của tôi, đó là tài liệu.

• Tài liệu thư viện. Các công cụ như Doxygen rất đơn giản và di động, không có lý do gì để không đưa cho tôi thứ gì đó tôi có thể tạo và duyệt.

• Tài liệu loại mờ trong tiêu đề công cộng. Dù sao tôi cũng sẽ tìm thấy chúng, nói cho tôi biết tại sao bạn không muốn tôi nhắn tin với chúng và điều gì có thể xảy ra nếu tôi làm vậy. Nếu bạn thực sự muốn các bản vá, tôi cần biết bạn đang nghĩ gì.

• Đừng thả và chạy. Tôi thực sự đánh giá cao những bình luận như "Xin vui lòng, đừng liên hệ với tôi về điều này. Tôi không có ý định duy trì nó. Điều này đã giải quyết vấn đề trước mắt của tôi, có thể nó sẽ giải quyết vấn đề của bạn. Tôi không quan tâm, tôi sẽ không cập nhật cái này và bạn có thể cảm thấy thoải mái khi ngã ba nó. " Tôi không thể nói cho bạn biết tôi tiết kiệm được bao nhiêu thời gian.

• Nó sẽ không thêm rò rỉ bộ nhớ hoặc lỗi cho mã hiện có. Nếu bạn không kiểm tra trước khi đẩy công cụ vào mã của riêng mình, tại sao bạn lại dụ dỗ tôi đẩy nó sang mã của tôi?

• Nếu đó thực sự là một thư viện, hãy sử dụng giấy phép cho phép và nhất quán. Đừng quyết định ba tháng nữa là bạn sẽ kiếm được nhiều tiền hơn từ nó. Điều đó vượt quá khó chịu vào đêm trước khi bạn gửi một cái gì đó và nhận ra rằng bạn phải viết lại một loạt mã thư viện vì giấy phép đã thay đổi. Đó chính xác là điều khiến tôi bực mình đủ để thực hiện lại công cụ của bạn theo giấy phép MIT.

• Hãy nhất quán trong phong cách mã hóa, những người khác phải đọc mã của bạn để tìm ra những gì nó thực sự làm khi mọi thứ không hoạt động như mong đợi.

• Không sử dụng hơn 110 cột, mã của bạn có thể phải được chỉnh sửa tại chỗ và tôi chỉ có thể có màn hình 80x25. Nếu bạn dựa vào các tab để làm cho mọi thứ trông 'thanh lịch' hơn, bạn có các vấn đề khác cần giải quyết.

• Cố gắng ít nhất là xem xét các cổng, nếu không xử lý một ngôn ngữ được dịch. Ngay cả sau đó, cố gắng ít nhất là xem xét các cổng.

• Cho tôi kiểm tra. Tôi hy vọng bạn có chúng, tôi có thể đề nghị chúng khác và tôi thực sự có thể giúp viết chúng dựa trên biểu đồ cuộc gọi. Nếu tôi vượt qua tất cả những rắc rối đó, vui lòng sử dụng chúng . Nếu không, bạn nhận được các bản vá "làm việc cho tôi !!!" :)

• Đừng phá vỡ API, thời gian. Tôi biết bạn có thể nhận ra rằng bạn đã sai về tất cả, nhưng hãy chắc chắn rằng những thứ liên kết đến bạn sẽ không bị hỏng trên một bản cập nhật đơn giản. Điều đó có thể có nghĩa là một số cruft và kydges, chào mừng đến với thế giới của các thư viện.

• Đưa cho tôi một lộ trình để tôi không nhân đôi công việc của bạn hoặc công việc của người khác.

Tôi có thể sẽ chỉnh sửa bài đăng này để thêm nhiều hơn nữa.

Tôi quan tâm nhiều hơn đến các tính năng mềm của API. Đó là:

• Sự đơn giản
• Tính nhất quán
• Thanh lịch
• Trực giác
• Nó chỉ hoạt động

Tôi có thể đúng một cuốn sách về cách áp dụng hoặc sẽ được triển khai, nhưng đủ để nói trừ khi người dùng API có thể xoay quanh cách sử dụng nó một cách hiệu quả, đó là cách sử dụng hạn chế. Đơn giản không có nghĩa là đơn giản, cũng như thanh lịch không có nghĩa là onate. Nó đơn giản có nghĩa là nó chỉ hoàn hảo cho công việc. Càng ít người phải suy nghĩ về cách sử dụng API, họ càng có thể sử dụng nó nhiều hơn.

Làm thế nào những cái này trông phụ thuộc vào lnaguage, mục đích và đối tượng mục tiêu của API. Các tiêu chí cuối cùng sôi sục theo nguyên tắc ít bất ngờ nhất. Không có lỗi mà bạn không mong đợi chúng. Mọi giải thích hợp lý về API sẽ giúp bạn có được kết quả như mong muốn.

Làm những điều đơn giản Những điều đơn giản và phức tạp có thể

Điều này khá nhiều tổng hợp mọi triết lý thiết kế khác. Nếu thư viện của bạn chỉ làm cho những điều phức tạp trở nên khả thi, những người tìm cách giải quyết 80% trường hợp sử dụng dễ dàng nhất sẽ được khuyến khích phát minh lại bánh xe thay vì đối phó với sự quái dị quá mức của bạn yêu cầu bạn sử dụng 6 lớp khác nhau để thực hiện tương tự thư viện của bạn Thế giới ".

Nếu thư viện của bạn chỉ làm cho những điều đơn giản trở nên đơn giản, mọi người sẽ trở nên khó chịu rất nhanh khi họ phát hiện ra rằng họ cần phải viết lại mã của họ chỉ vì họ có một yêu cầu hơi lạc lõng.

Các cách tốt nhất để thực hiện điều này là:

• Hãy tự do trong những gì bạn chấp nhận. Nếu bạn đang lập trình bằng ngôn ngữ động, hãy sử dụng gõ vịt để có hiệu lực đầy đủ. Nếu bạn đang lập trình trong C ++ hoặc D, hãy sử dụng các mẫu bất cứ khi nào có thể. Chấp nhận bất cứ điều gì thỏa mãn một số giao diện cấu trúc phổ quát hợp lý. Đừng ép người dùng của bạn thực hiện nhiều công việc bận rộn chuyển đổi dữ liệu từ định dạng này sang định dạng khác.

• Xây dựng chức năng tiện lợi cấp cao vào thư viện của bạn, nhưng xây dựng nó một cách minh bạch trên chức năng cấp thấp hơn và đảm bảo chức năng cấp thấp hơn có sẵn cho những người cần nó.

• Theo nguyên tắc ít gây ngạc nhiên theo mặc định, ngay cả khi làm như vậy có thể hạn chế tính linh hoạt hoặc hiệu quả. Nếu cần thiết, hãy thêm một chức năng thứ hai với một tên dài dòng hơn, nhấn mạnh sự đáng ngạc nhiên của nó để cho phép tối ưu hóa hoặc tăng tính linh hoạt.

• Đóng gói là hữu ích, nhưng đừng lo lắng về nó. Đôi khi, những người có yêu cầu bất thường, không lường trước được có thể cần phải nhận được bên dưới một trong những điều trừu tượng của bạn để hoàn thành công việc. Mặt khác, thật khó để bắn vào chân mình một cách tình cờ, khi sử dụng các cấu trúc dường như vô hại . Hãy ghi nhớ điều này khi quyết định mức độ chặt chẽ của bạn muốn khóa công cụ.

• Sử dụng các ví dụ rất nhiều trong tài liệu của bạn. Điều này phục vụ cả hai để minh họa các trường hợp sử dụng phổ biến cho người dùng của bạn và buộc bạn phải suy nghĩ xem liệu các trường hợp phổ biến nhất có được sắp xếp hợp lý hay không.

• Mặc định hợp lý cho mọi thứ bạn có thể, nhưng hãy đảm bảo rằng các mặc định đó chỉ là mặc định và đó là cách rõ ràng để ghi đè chúng.

• Hợp lý, tối giản lành mạnh

Đó là tất cả. So sánh, ví dụ, cơ chế của các đường ống trên Windows và UNIX. Một cung cấp một loạt các hàm API chuyên dụng với một loạt các đối số tối nghĩa, không cần thiết hoặc hiếm khi được sử dụng, mỗi đối số có thể có một trong nhiều giá trị macro / hằng. Về cơ bản UNIX sử dụng lại giao diện mở / đọc / ghi / đóng hiện có, cộng với một vài phương thức rất đơn giản cho một số trường hợp cụ thể, chẳng hạn như socketcharge () hoặc pipe (). Thực sự gần như không có gì mới, bạn nên tìm hiểu để sử dụng các đường ống trên UNIX. Bây giờ so sánh với điều này .

(Công bằng mà nói, Microsoft ban đầu chỉ "mượn" giao diện đó từ HĐH của IBM / 2.)