API Design Principles
Consistent, intuitive, and powerful APIs are among the most well-known strengths of Qt. This article outlines the best practices we have developed over the years while designing Qt-style APIs. Many of these guidelines are general principles, while others are more specific and primarily aim to maintain consistency with existing APIs.
Although these guidelines are mainly intended for external APIs, it is also recommended to apply similar techniques when designing internal (private) APIs. This helps promote better collaboration between developers and ensures a more uniform codebase.
For those interested in learning more, you can also refer to Jasmin Blanchette’s "Little Manual of API Design" (PDF) or Matthias Ettrich’s "Designing Qt-Style C++ APIs."
1. Six Traits of a Good API
An API serves as a bridge between a programmer and an end-user. The "P" in API actually stands for "Programmer," not "Program," emphasizing that APIs are designed for developers, not machines.
In the 13th issue of Qt Quarterly, Matthias Ettrich introduced the idea that APIs should be minimal, complete, clear, intuitive, easy to remember, and guide users toward writing readable code.
1.1 Minimalist
A minimalist API means that each class has as few public members as possible, and as few public classes overall. This makes the API easier to understand, remember, debug, and evolve over time.
1.2 Complete
A complete API includes all the necessary features. However, this can sometimes conflict with keeping the API minimal. If a function is placed in the wrong class, users might not find it, which violates the principle of completeness.
1.3 Clear and Simple Semantics
Like any good design, APIs should follow the principle of least surprise. A great API should make common tasks easy, allow for less common operations without overcomplicating things, and solve specific problems rather than generating generic solutions unnecessarily. For example, in Qt 3, QMimeSourceFactory should not have been named QImageLoader with a different API.
1.4 Intuitive
An API should feel natural and intuitive. While personal experience and background may influence what feels intuitive, the true test of intuitiveness is whether a less-experienced user can grasp the API without reading documentation, and whether a developer can understand code using the API without prior knowledge of it.
1.5 Easy to Remember
To make an API easy to remember, naming conventions should be consistent and accurate. Use recognizable patterns and avoid abbreviations where possible.
1.6 Guide Users to Write Readable Code
Code is written once but read many times. Writing readable code takes more time initially, but it saves time throughout the product's lifecycle.
Keep in mind that different users will use different parts of the API. While it's intuitive to use a single Qt class, it's reasonable to expect users to consult documentation if they need to inherit a class.
2. Static Polymorphism
Similar classes should have similar APIs. This can be achieved through inheritance when appropriate, which is known as runtime polymorphism. However, polymorphism can also occur during the design phase. For instance, replacing QSlider with QProgressBar or QByteArray with QString shows how similar APIs make replacement easier—this is called "static polymorphism."
Static polymorphism simplifies memory management and programming patterns. Therefore, a group of related classes with similar APIs is often preferable to each having its own unique set of APIs.
In Qt, we generally prefer static polymorphism unless there's a strong reason to use inheritance. This reduces the number of public classes in Qt and helps new users navigate the documentation more easily.
2.1 Good Example
QDialogButtonBox and QMessageBox share similar APIs for handling buttons (such as addButton(), setStandardButtons(), etc.), and they don’t need to inherit from a common base class like QAbstractButtonBox.
2.2 Poor Example
Both QTcpSocket and QUdpSocket inherit from QAbstractSocket, but their interaction models are very different. It seems no one has found a meaningful way to use QAbstractSocket pointers in a generic manner.
2.3 Cases Worth Considering
QBoxLayout is the parent class of QHBoxLayout and QVBoxLayout. The benefit is that you can use QBoxLayout on a toolbar and call setOrientation() to switch between horizontal and vertical layouts. However, the downside is an extra class, which may lead to confusing code like ((QBoxLayout *)hbox)->setOrientation(Qt::Vertical).
SC/PC Fiber Optic Fast Connector
Sc/Pc Fiber Optic Fast Connector,Fast Fiber Connector Kit,Quick Connect Fiber Connectors,Sc Quick Connector
Ningbo Fengwei Communication Technology Co., Ltd , https://www.fengweicommunication.com