"Designing Qt-Style C++ APIs" 笔记

(一直有听说, Qt 的 API 设计很出色, 这篇文章以前看过, 最近试着用 Qt 做开发, 所以再看一遍)

An API is to the programmer what a GUI is to the end-user. The 'P' in API stands for "Programmer", not "Program", to highlight the fact that APIs are used by programmers, who are humans.
很巧的是, 与之前 Ken Arnold 一篇访谈 中给出的 "programmers are people." 观点非常一致

接下来, 讲了优秀的 API 需要具备的 6 大特质:
Be minimal, Be complete, Have clear and simple semantics, Be intuitive, Be easy to memorize, Lead to readable code
(想起读书时, 老师讲过的设计一个规则体系的 3 大原则: 1. 尽可能少 2. 完备 3. 不能相互冲突)

上面讲的, 只是好的 API 具备的特性. 在设计及改进 API 时, 可以拿来, 作为参考, 评判的标准.
下面是一些比较具体的建议了.

The Convenience Trap
It is a common misconception that the less code you need to achieve something, the better the API. Keep in mind that code is written more than once but has to be understood over and over again.

不想强调得更多. 不只是设计 API 需要注意这点, 日常写代码一样需要注意.

 

以 C# 的 var 为例, 有人鼓吹, 可以少写很多类型声明的代码, 让生活更美好云云(听说 ReSharper 也把这个作为推荐风格了...). 先不说现代 IDE 强大的自动补全, 根本不需要大爷您敲多少按键. 您大爷的有没有想过, 您写起来是方便了, 别人看您代码会有多难过? 别跟我说, 现在的 IDE 都有即指即译功能, 扫一眼代码, 还需要一个变量一个变量用鼠标去指, 累不累?

 

对于目前打着"简便"名义流行的种种势头, 我都不是非常信服, 因为:

1. 提倡者都讲 coding 时的便利, 对于 readability 很少涉及.

2. 脚本编程不是什么新鲜玩意, 但缺少大型系统开发, 维护方面的说服力.

3. 我认为很多这种观点后面隐藏了一个乐观(天真?)的前提, 即所有人都能够写出易于理解, 易于维护的代码. 对此, 我只想说, 欢迎来到地球.

 

当然, 我并不是认为这些趋势不好, 要抵制他们, 相反, 如果真的能降低编程的难度, 改善大家的生活, 我当然很乐意. 但我需要更多的, 更详细的证据, 而不是几篇布道式的文章.

(或许, 这就是 you can't teach an old dog new tricks? 难道, 不知不觉, 已经老了? 杯具...)

 

The Boolean Parameter Trap

Boolean parameters often lead to unreadable code.

 

乍一看, 很细节的要求, 但可读性未尝不是源于这些细节的优化? 避免 magic number 同样也是很细节的要求.

或许我需要更改自己的观念了.

 

Static Polymorphism

不明白作者想说明什么

 

The Art of Naming

Naming is probably the single most important issue when designing an API.

 

关于命名, 可以说的太多了. 从 Qt 的 API 设计经验出发, 作者讲一些很实际的观点:

 

General Naming Rules

A few rules apply equally well to all kinds of names.

First, as I mentioned earlier, do not abbreviate.(Things naturally get worse if the API itself is inconsistent)

 

Another important but more subtle rule when designing classes is that you should try to keep the namespace for subclasses clean .

 

Naming Classes

Identify groups of classes instead of finding the perfect name for each individual class.

 

Naming Enum Types and Values

When declaring enums, we must keep in mind that in C++ (unlike in Java or C#), the enum values are used without the type.

 

因此要避免在 enum 的 value 中使用太通用的名称.

记得以前写 c++ 时, 用过一个技巧, 把 enum 定义在 class 中, 使用的时候就是 EnumClass::EnumValue.

 

Naming Functions and Parameters

The number one rule of function naming is that it should be clear from the name whether the function has side-effects or not.

 

是吗?

 

Parameter names are an important source of information to the programmer.

 

Naming Boolean Getters, Setters, and Properties

Finding good names for the getter and setter of a bool property is always a special pain.

 

似乎没什么好办法, 看情况处理.

 

Pointers or References?

Most C++ books recommend references whenever possible, according to the general perception that references are "safer and nicer" than pointers. In contrast, at Trolltech, we tend to prefer pointers because they make the user code more readable.

    color.getHsv(&h, &s, &v);
    color.getHsv(h, s, v);

Only the first line makes it clear that there's a high probability that h, s, and v will be modified by the function call.

验证了我上面的观点, 很多时候, 提建议的人并不知道他们自己在说什么, 偏偏很多初学者会被这些似是而非的观念误导, 直到自己碰壁了, 才幡然醒悟.

最后的总结性发言:

 

How to Get APIs Right

 

APIs need quality assurance. The first revision is never right; you must test it. Make use cases by looking at code which uses this API and verify that the code is readable.

 

Documenting is also a good way of finding good names when you get stuck.

If you cannot find a precise name, this is often a sign that the item shouldn't exist.

 

关于 API 的设计, 这篇文章讲的很不错, 既有理论, 也有实际的经验.

 

同时, 也看得出来, Qt 的同学在提供一个好的开发框架方面, 确实下了很大的心血, 并且能够将他们的经验分享给大家, 非常感谢.

 

btw. joshua bloch 也有一篇关于 API 设计的讲稿不错, 推荐下 <<How to Design a Good API and Why it Matters>>, 没有链接, 感兴趣的同学自己 google 之