The API is to the programmer what the GUI is to the end user.
BUT: remember minimization. make sure the feature really belongs into the class.
many potential users of the function won't find it.
As with any other design work: apply the principle of least surprise.
Make common tasks easy, and rare tasks possible.
If you are not sure about something, remove it. Add it later, when you fully understand it.
Intuition is based on experience, different experience and background leads to different perception on what is and is not intuitive.
if a semi-experienced Qt-user gets away without reading the docs.
if a programmer who does not know Qt can understand code written against it.
Choose consistent and presise naming.
Avoid words that are unknown to non-native speakers.
Use recognizable patterns and concepts.
Rationale: Code is written once, but read/debugged/understood many many times.
=> Readable code may sometimes take longer to write, but safes time throughout the code lifecycle.
Usage should be "intuitive", subclassing may require reading the docs.
Component authors are expected to have a higher level of conceptual understanding.
Missconception: The fewer code necessary to achieve something, the better the API.
Remember: Code is written once, but read/debugged/understood many many times.
Broken rationale: Adds no extra function thus no extra bloat, no need to document another function, no need to adjust the class documentation, simple.
Truth: Adds bloat (to a function, not a class), hard to memorize, leads in non-intuitive code.
Similar classes should have a similar to identical API.
Extrem position: Similar classes should implement the same interface or a common base class. This allows runtime polymorphism.
But: A similar to identical API also makes sense without. Rationale: Polymorphism also happens at design time.
A similar API for a set of related classes is better than perfect individual APIs for each class.
The first revision of an API is never right, you must test APIs.
Make use cases, carefully study code that uses the API (an API is beautiful if the code written against it is beautiful).
Have somebody else use it with/without documentation.
Document it. For classes, don't just write functional documentation, but a class overview that covers the entire API. Basic rule: if this is really really hard, then the class has problems.
Get your names right, names are as important as good documentation is.
Do not abbreviate, unless the term is commonly used.
Use more elobarate names for specific features of classes that are intended for subclassing.
Example: windowTitle as opposed to title or caption.
Consider what caption or title might mean for group box or menu.
Keep the namespace for subclasses clean.
Document the item and use your first sentence as inspiration.
Talk to a friend or your dog and explain what the item does.
Invent a new name. Examples: widget, focus, buddy (but only if everything else fails and you are convinced that the concept makes sense).
Don't state the obvious, remove redundant parts Example: QLabel instead of QLabelWidgetObject.
Identify groups of classes instead of finding the perfect name for each individual class.
Leverage knowledge and experience that potential users have from other toolkits.
Parameter names are an important source of information to the programmer, almost as important as member names.
Describe a parameter's meaning rather than a parameter's type.
Rule of thumb: "is" for singular adjectives, and no prefix otherwise.
Never use the third person.
Task: HTML-rendering widget should have a property that indicates whether it underlines links or not.
Objects belong on the heap, values on the stack. Pointers to values should not normally happen (QString*, QPixmap*).
Const references are good, non-const references are bad for readability. Use pointers for out-parameters instead and mark the function with get.
Discovery: QProgressBar is similar to QAbstractSpinBox and its subclasses QSpinBox, QSlider and QDial.
centerIndicator and indicatorFollowsStyle are two boolean value to define alignment. Qt uses this on many places: we have AlignLeft, AlignCenter and AlignAuto. AlignRight must be supported anyway for right-to-left locales.
QProgressBar makes it possible for subclasses to change the text.