API Design Principles

Original link: API Design principles–qt Wiki
Based on Gary's influence on Gary Gao's translation: API design guidance for C + +

QT's design level is well-known in the industry, consistent, easy to master and powerful API is one of QT's most famous advantages. This article is the QT official web API design guidelines, but also QT in the API design practice summary. Although QT uses C + +, the design principles and thinking are universal (if you are not proficient in C + +, you can ignore the strong or overly detailed parts of C + +, you can still learn or comb about the most valuable content of the API design). There are a lot of examples in the entire space, a rare good article on API design.

It is important to note that some of the content of this wiki is not complete, so there may be some reading problems, and we have some comments about it.

PS: There will certainly be deficiencies and mistakes in translation, Welcome to comment & Exchange; The source code in this warehouse of GitHub, can submit issue/fork after submitting to suggest/correct. API Design Principles

Consistent, easy-to-master, and powerful APIs are one of the best known features of Qt. This article summarizes the tricks that we have accumulated in the process of designing QT-style APIs (know-how). Many of them are general guidelines, while others are more in agreement, and follow these conventions primarily to align with existing APIs.

While these guidelines are primarily intended for external APIs (public APIs), it is also recommended to follow the same technique (techniques) when designing an internal API (private API) as a courtesy of collaboration between developers (courtesy).

If interested, you can also read Jasmin Blanchette's little Manual of API Design (PDF) or Matthias Ettrich C + + APIs from the predecessor of this article designing Qt-style.

1.6 qualities of a good API

The API to programmers is like a graphical interface to a normal user (end-user). The "P" in the API actually refers to "programmer" (Programmer), not "program", which emphasizes the fact that the API is used by programmers.

In the 13th edition of the QT Quarterly, Matthias's article on API design suggests that the API should be minimalist (minimal) and complete, with clear semantics (with clear and simple semantics), and intuitive (be Intuitive), easy-to-remember (be easily to memorize), and bootstrap API users to write readable code (lead to readable codes). 1.1 Minimalism

The minimalist API is that each class has as few public members as possible, and the public class is as small as possible. Such APIs are easier to understand, memorize, debug, and change. 1.2 Complete

A complete API is a feature that is expected to be included. This can be a bit of a conflict with keeping the API minimalist. If a member function is placed in the wrong class, then the potential user of the function will not be found, which is also a violation of completeness. 1.3 Clear and simple semantics

Like other designs, we should observe the least-surprising principle (the principle of least surprise). A good API should make it easier to do common things, and have the possibility of accomplishing uncommon things, but not focusing on the uncommon. The solution is a specific problem; do not over-generalize the solution when there is no need. (for example, in QT 3, qmimesourcefactory should not be named Qimageloader and have different APIs.) ) 1.4 in line with intuition

Just like everything else in a computer, APIs should be intuitive. People with different experiences and backgrounds have different opinions about what is not compatible with intuition. API's Intuitive testing approach: inexperienced users can understand the API without having to read the API documentation, and programmers can see the code using 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-identify patterns and concepts, and avoid abbreviations. 1.6 Guide API consumer to write readable code

The code is written only once, but it is read multiple times (with 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. While simple use of an instance of a single QT class should be intuitive, if you are inheriting a class, it is a reasonable requirement for the user to be optimistic about the document beforehand. 2. Static polymorphism

Similar classes should have similar APIs. Inheritance can be used to achieve this effect when inheritance (inheritance) is appropriate, that is, run-time polymorphism. However polymorphism also occurs in 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 the substitution easy. This is called "Static polymorphism" (polymorphism).

Static polymorphism also makes memory APIs and programming patterns easier. Therefore, a group 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 tend to use static polymorphism. This reduces the number of QT public classes and makes it more directional for users who are just learning QT to look through the document. 2.1 Good Cases

Qdialogbuttonbox and Qmessagebox have similar APIs on processing buttons (AddButton (), Setstandardbuttons (), and so on) and do not need to inherit from a Qabstractbuttonbox class. 2.2 cases of poor

Both Qtcpsocket and qudpsocket inherit Qabstractsocket, which is a very different pattern of the interaction behavior of the two classes (mode of interaction). No one seems to have used the qabstractsocket pointer in a generic and meaningful way (or can use the Qabstractsocket pointer in a generic and meaningful way). 2.3 Cases worthy of deliberation

Qboxlayout is the parent class of Qhboxlayout and Qvboxlayout. Benefit: You can use qboxlayout on the toolbar, call SetOrientation () to make it horizontal/vertical. Cons: One more class, and it's possible to cause the user to write a code that doesn't make sense ((Qboxlayout *) hbox)->setorientation (qt::vertical). 3. Attribute-based APIs

The new QT class tends to use the attribute-based API, such as:

1 2 3 4

Qtimer timer; Timer.setinterval (1000); Timer.setsingleshot (TRUE); Timer.start ();

The attribute here refers to any conceptual feature (conceptual attribute), which is part of the state of the object-whether it is q_property or not. In a way that makes sense, the user should be able to set properties in any order, that is, the attributes should be orthogonal (orthogonal). For example, the above code can be written as: