你如何定义一个好或坏的API？ [英] How do you define a good or bad API?

问题描述

我在我的大学被称为软件约束服用一类。在第一个讲座我们学习如何建立良好的API。

I am taking a class at my university called "Software Constraints". In the first lectures we were learning how to build good APIs.

我们得到了一个非常糟糕的API函数的一个很好的例子是插座公共静态无效的选择（的IList的checkRead，IList的checkWrite，IList的checkError，INT微秒）;在C＃ 。该函数接收插座3列出，并破坏它们使用户有他们送入选择（）之前克隆所有插座。它也有一个超时（微秒），这是一个int，即设置最大时间服务器可以等待一个插座。这样做的限度为±35分钟（因为它是一个int）。

A good example we got of a really bad API function is the socket public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); in C#. The function receives 3 lists of sockets, and destroys them making the user have to clone all the sockets before feeding them into the Select(). It also has a timeout (in microseconds) which is an int, that sets the maximum time the server can wait for a socket. The limits of this is +/-35 minutes (because it is an int).

---

1. 你是如何定义的API作为
   '坏'？


2. 你如何定义
   API作为'好'？

---

是很难
• 函数名记。

是很难
• 功能参数理解。


• 坏文件。


• 一切是如此相互关联的，如果您需要更改1线$ C $的c您实际上需要改变数百行的其他地方。


• ，破坏他们的参数的函数。


• 坏的可扩展性，由于隐藏的复杂性。


• 它从用户的/ dev需要围绕该API的包装，以便它可以被使用。

推荐答案

在API的设计，我一直觉得这个主题非常有帮助：搜索
如何设计一个好的API和重要性 - 由Joshua布洛赫

In API design I've always found this keynote very helpfull:
How to Design a Good API and Why it Matters - by Joshua Bloch

下面是摘录，我建议你阅读了整个事情/看视频。

Here's an excerpt, I'd recommend reading the whole thing / watching the video.

二。总则

  
• API应该做的一件事，把它做好搜索

  
• API应该是尽可能小但年纪也不小了结果

  
• 实施并不会影响到API结果

  
• 最小化的一切无障碍结果

  
• 名字有关系-API是一个小语言搜索

  
• 文档事项结果

  
• 文档宗教上搜索

  API设计决策
• 考虑性能后果结果

  
• 在性能API设计决策的影响是真实的，永久结果

  
• API必须与平台和平共处

  

三。类的设计

  
• 最小化可变性结果

  
• 子类只有在它是有道理的结果

  
• 设计和文档的继承或否则禁止它

  

IV。方法设计

  
• 请不要使客户端做任何事模块可以干得结果

  
• 不得违反原则最小惊讶的结果

  
• 快速失败 - 报告错误作为后应尽快它们发生结果

  
• 提供的所有数据可在字符串表 -
编程访问
  
• 超载小心结果

  
• 使用适当的参数和返回类型结果

  
• 使用一致的参数排序方法对面结果

  
• 避免长参数列表结果

  
• 避免这一需求特殊处理返回值

  

• Don't Make the Client Do Anything the Module Could Do
  
• Don't Violate the Principle of Least Astonishment
  
• Fail Fast - Report Errors as Soon as Possible After They Occur
  
• Provide Programmatic Access to All Data Available in String Form
  
• Overload With Care
  
• Use Appropriate Parameter and Return Types
  
• Use Consistent Parameter Ordering Across Methods
  
• Avoid Long Parameter Lists
  
• Avoid Return Values that Demand Exceptional Processing

这篇关于你如何定义一个好或坏的API？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！