Perfect API Design

Perfect API Design
良好的API设计规范

为什么设计良好的应用程序接口（API）总是很难设计，接口并不仅仅是定义一些类还有方法，可以使用就OK了。这样只有设计者知道如何使用，不规范的接口会被其他的程序员抱怨，或者会被作为反例来进行介绍。那么如何规避这些问题，如何设计出良好的API哪？

Tivo具有非常好的接口设计：

Usage is simple
Misuse is difficult
TiVo does one thing well
It does not do anything unexpected
It has never crashed in multiple years of usage
Actions/tasks are intuitive and easy to discover
The UI is consistent, polished and perfect, or close to it

用法简单
易理解，易上手
做好重要功能
并没有期待能做好所有事情
在长达几年的使用中系统不会崩溃
功能很直观，很容易被发现
统一的UI设计

HRESULT Exec ( 
    const GUID *pguidCmdGroup,  // Pointer to command group
    DWORD nCmdID,                   // Identifier of command to execute
    DWORD nCmdExecOpt,          // Options for executing the command
    VARIANTARG *pvaIn,            // Pointer to input arguments
    VARIANTARG *pvaOut           // Pointer to command output
);

设计应用程序接口（API）的设计也因该遵循这样的原则。让我们来看来自COM的一个例子：IOleCommandTarget::Exec。这个API通常被用来执行某个命令。