General guidelines and agreed guidelines in the API design process

Consistent, easy to grasp and powerful APIs are one of Qt's most famous advantages. This article summarizes the know-how that we accumulated during the design of the Qt-style API. Many of them are general guidelines; others are more biased, and they are primarily intended to be consistent with existing APIs.

Although these guidelines are mainly used for external APIs, it is recommended to follow the same techniques (techniques) when designing the internal API (private API) as a courtesy for collaboration between developers.

If you are interested, you can also read Jasmin Blanchette's Little Manual of API Design (PDF) or the design of this article, Matthias Ettrich's Designing Qt-Style C++ APIs.

1. 6 traits of good API

The API is like a programmer to a graphical user to an end-user. The "P" in the API actually refers to the "Programmer" rather than the "Program", emphasizing the fact that the API is for programmers.

In the 13th Qt Quarterly, Matthias' article on API design puts forward the idea that APIs should be minimal and complete, have clear and simple semantics, be intuitive, Be easy to memorize and guide API users to write to readable code.

1.1 Minimalist

The minimalist API means that there are as few public members as possible for each class, and as few public classes. Such an API is easier to understand, remember, debug, and change.

1.2 Complete

A complete API means that all the desired features are included. This will be somewhat inconsistent with keeping the API minimal. If a member function is placed in the wrong class, the potential user of the function will not be found, which is also a violation of completeness.

1.3 Semantic clarity and simplicity

Like other designs, we should follow the principle of least surprise. A good API should make common things easier to accomplish, and have the possibility to do things that are not common, but don't focus on things that are not common. Solve specific problems; don't overgenerate solutions when there is no demand. (For example, in Qt 3, QMimeSourceFactory should not be named QImageLoader and has a different API.)

1.4 Intuitive

Just like everything else in the computer, the API should be intuitive. For those who are inconsistent with what is not true, people with different experiences and backgrounds will have different opinions. The API is intuitively tested: users with less-experienced APIs can understand the API without having to read the API documentation, and programmers can understand the code that uses the API without knowing the API.

1.5 easy to remember

To make the API easy to remember, the API naming convention should be consistent and accurate. Use easy-to-recognize patterns and concepts and avoid using abbreviations.

1.6 Guide API user to write readable code

The code is written only once, but it has to be read multiple times (and debugging and modification). Writing readable code sometimes takes more time, but it saves time for the entire life cycle of the product.

Finally, keep in mind that different users will use different parts of the API. Although it is intuitive to simply use an instance of a single Qt class, it is a reasonable requirement to have the user prioritize the document if it is to inherit a class.

Similar classes should have similar APIs. This effect can be achieved with inheritance when inheritance is appropriate, ie runtime polymorphism. However, polymorphism also occurs during the design phase. For example, if you replace QSlider with QProgressBar, or replace QByteArray with QString, you will find that the similarity of the API makes it easy to replace. This is called "static polymorphism".

Static polymorphism also makes memory APIs and programming modes easier. Therefore, a set of related classes with similar APIs is sometimes better than each class has its own set of APIs.

In general, in Qt, if there is not enough reason to use inheritance, we prefer to use static polymorphism. This can reduce the number of Qt public classes, and also makes the user who just learned Qt more direction when looking through the document.

2.1 Good case

QDialogButtonBox and QMessageBox have similar APIs on the processing buttons (addButton(), setStandardButtons(), etc.) and do not need to inherit a QAbstractButtonBox class.

2.2 Poor case

Both QTcpSocket and QUdpSocket inherit QAbstractSocket, and the mode of interaction of these two classes is very different. No one seems to have used QAbstractSocket pointers in a generic and meaningful way (or can use QAbstractSocket pointers in a generic and meaningful way).

2.3 Cases worth considering

QBoxLayout is the parent class of QHBoxLayout and QVBoxLayout. Benefit: You can use QBoxLayout on the toolbar and call setOrientation() to make it horizontal/vertical. The downside: there is one more class, and it is possible to cause the user to write code that makes no sense, ((QBoxLayout *)hbox)->setOrientation(Qt::Vertical).

Harbour Marine Diesel Generator

Harbour Marine Diesel Generator,Onshore Marine Generator,Offshore Marine Generator,Marine Engine

Jiangsu Vantek Power Machinery Co., Ltd , https://www.vantekpower.com