Designing Qt-Style C++ APIs

Материал из Wiki.crossplatform.ru

Текущая версия на 08:16, 26 марта 2010

Qt Quarterly | Выпуск 13 | Документация

от Матиаса Этриха

Мы закончили важное исследование в Trolltech, связанное с улучшением процесса разработки Qt. В этой статье я хочу поделиться некоторыми нашими находками и представить принципы, которые мы использовали при проектировании Qt4, а также показать вам, как использовать их в вашем коде.

Проектирование интерфейсов программирования - сложная задача. Это такое же сложное искусство, как проектирование языков программирования. Существует множество различных принципов построения API (Application Programming Interface, интерфейс прикладного программирования), многие из которых конфликтуют друг с другом.

В настоящее время компьютерные науки уделяют много внимания алгоритмам и структурам данных, упуская из вида принципы проектирования языков программирования и фреймворков. Это упущение является причиной неподготовленности программистов к задаче, которая встает перед ними все чаще и чаще: создание компонентов повторного использования.

Перед расцветом объектно-ориентированных языков программирования код многократного использования писался главным образом производителями библиотек, а не разработчиками ПО. В мире Qt эта ситуация основательно изменилась. Программирование на Qt - это постоянная разработка новых компонентов. Типичное приложение на Qt содержит ряд собственных компонентов, которые повторно используются во всех частях программы. Часто эти же компоненты являются частью другого приложения. В KDE пошли дальше и расширили Qt множеством библиотек, которые реализуют сотни дополнительных классов.

Но что же определяет хороший и эффективный C++ API? Хороший он или плохой, зависит от многих факторов - например, задача и специфические цели. Хороший API имеет ряд характерных свойств. Наличие некоторых, как правило, является желательным, а наличие других определяется спецификой конкретной сферы.

[править] Шесть характеристик хорошего API

API для программиста - это тоже самое, что и пользовательский интерфейс (GUI) для конечного пользователя. Под буквой 'P' в сокращении API имеется ввиду "Программист", не "Программа", подчеркивая тот факт, что API используются программистами (которые являются людьми).

Мы считаем, что API должны быть компактным и законченным, иметь ясную и простую семантику, быть интуитивными, легко запоминаться, и приводить к читаемому коду.

• Быть компактным: Компактный API подразумевает минимальное количество как публичных членов класса, так и самих классов. Это позволяет легче понимать, запоминать, отлаживать и изменять API.
• Быть законченным: Законченный API подразумевает, что в нем заключен ожидаемый функционал. Это правило может конфликтовать с компактностью. Также, если функция-член находится не в том классе [в котором ожидалось], то многие потенциальные пользователи не найдут эту функцию.
• Иметь ясную и простую семантику: Как и в других видах проектирования, вы должны идти по пути наименьшего удивления. Делайте выполнение стандартных задач простым. Выполнение редких задач также должно быть возможным, а не являться фокусом. Решайте конкретную задачу; не делайте решение слишком общим, если этого действительно не требуется. (Например, QMimeSourceFactory в Qt3 мог бы называться QImageLoader и иметь другой API)
• Быть интуитивным: как и другие вещи в компьютере, API должен быть интуитивным. Опыт и различные предпосылки приводят к различному восприятию того, что является интуитивным, а что - нет. API является интуитивным, если пользователь среднего класса начинает работу без чтения документации, и если программист, не знающий API, может понять исходный код, написанный с использованием этого API.
• Быть легко запоминаемым: Чтобы сделать API простым для запоминания, выберите согласованную и точную политику именования. Используйте узнаваемые шаблоны и концепции, и избегайте сокращений.
• Способствовать лёгкой читаемости кода: Код пишется однажды, но читается (и отлаживается, и изменяется) множество раз. Иногда написание легко читаемого кода может занять много времени, но это в результате сэкономит время в течении всего жизненного цикла продукта.

Наконец, имейте в виду, что разные пользователи будут использовать различные части вашего API. В то время как использование экземпляров классов Qt должно быть интуитивно понятным, логично предполагать, что пользователь прочтет документацию перед использованием класса.

[править] Ловушки удобства

Существует распространенное заблуждение, что чем меньше кода вы пишите для решения задачи, тем лучше API. Имейте ввиду, что код пишется однажды, но должен быть понят много раз. Например

QSlider *slider = new QSlider(12, 18, 3, 13, Qt::Vertical,
                              0, "volume");

намного сложнее прочитать (и даже написать), чем

QSlider *slider = new QSlider(Qt::Vertical);
slider->setRange(12, 18);
slider->setPageStep(3);
slider->setValue(13);
slider->setObjectName("volume");

[править] Ловушки булевых параметров

Булевые параметры часто приводят к не читаемому коду. В частности, практически всегда будет ошибкой добавление булевого параметра в функцию. В Qt, традиционным примером является функция repaint(), которая принимает не обязательный булевый параметр, указывающий, должен ли очищаться задний фон (по умолчанию) или нет. Это приводит к такому коду:

widget->repaint(false);

который новички могут прочитать как "Не перерисовывать!"

Идея, по-видимому, состоит в том, что применение булевого параметра избавит от создания еще одной функции, что, в свою очередь, приведет к сокращению программного кода. На деле же - наоборот; сколько пользователей Qt "спиной почувствует", что делает каждая из следующих строчек?

widget->repaint();
widget->repaint(true);
widget->repaint(false);

Более качественный API:

widget->repaint();
widget->repaintWithoutErasing();

В Qt4 мы решили эту проблему просто исключив возможность перерисовки без очистки виджета. Qt4 поддерживает двойную буферизацию, что делает это свойство не актуальным.

Еще ряд примеров:

widget->setSizePolicy(QSizePolicy::Fixed,
                      QSizePolicy::Expanding, true);
textEdit->insert("Where's Waldo?", true, true, false);
QRegExp rx("moc_*.c??", false, true);

Очевидным решением является замена булевых параметров перечислениями (enum types). Так мы поступили с регистрозависимыми строками QString. Сравните:

str.replace("%USER%", user, false);               // Qt 3
str.replace("%USER%", user, Qt::CaseInsensitive); // Qt 4

[править] Статический полиморфизм

Похожие классы должны иметь схожий API. Этого можно добиться с помощью наследования, где это имеет смысл, то есть когда используется полиморфизм времени выполнения (run-time polymorphism). Но полиморфизм также имеет место быть и при проектировании. Например, если бы вы заменили QListBox на QComboBox или QSlider на QSpinBox, то обнаружили бы, что похожие API способствовали более легкой замене. Вот что мы называем "статическим полиморфизмом".

Статический полиморфизм также позволяет легче запомнить API и шаблоны программирования. Как следствие, похожие API для ряда связанных классов является более предпочтительным, чем индивидуальный безупречный API для каждого класса в отдельности.

[править] Искусство задания имен

Задание имен, возможно, является единственным наиболее важным вопросом при проектировании API. Каким образом задавать имена классов? Как назвать методы класса?

[править] Общие правила именования

Ряд правил применим в равной степени ко всем типам имен. Во-первых, как я упоминал ранее, не используйте сокращения. Даже явные сокращения, например, "prev" для "previous" не окажут должного эффекта, так как пользователь должен запомнить, что слова сокращены.

Дела пойдут плохо, если API не логичный; например, в Qt3 есть activatePreviousWindow() и fetchPrev(). Правило "без сокращений" поможет написать логичный API.

Другое важное, но не очевидное правило, при проектировании классов - вы должны постараться сохранить ясное пространство имен подклассов. В Qt3 не всегда следовали этому правилу. Чтобы продемонстрировать это, мы приведем в пример класс QToolButton. Что вы ожидаете при вызове методов name(), caption(), text() или textLabel() класса QToolButton? Просто попробуйте поиграть с QToolButton в Дизайнере форм:

• Свойство name наследуется от QObject и указывает на имя внутреннего объекта, которое может быть использовано для отладки и тестирования.
• Свойство caption наследуется от QWidget и указывает на заголовок окна, который не имеет значения для QToolButton, так как обычно он создается внутри родительского виджета.
• Свойство text наследуется от QButton и обычно используется на кнопке, если useTextLabel ложно.
• Свойство textLabel объявленно в QToolButton и отображается на кнопке, если useTextLabel истинно.

В Qt4 в интересах удобочитаемости свойство name у QToolButton названо objectName, свойство caption стало windowTitle и textLabel изменено на text.

[править] Имена классов

Определите группы классов вместо того, чтобы придумывать имя для каждого отдельного класса. Например, все классы, основанные на поэлементном представлении данных, в архитектуре Модель/Представление (Model/View) имеют суффикс View ( QListView, QTableView и QTreeView), а соответствующие им виджеты имеют суффикс Widget ( QListWidget, QTableWidget и QTreeWidget).

[править] Имена типов перечислений и их значений

При объявлении перечисления нужно помнить, что в C++ (в отличии от Java или C#), их значения не имеют типа. Следующий пример показывает опасность задания слишком общих имен значений перечисления:

namespace Qt
{
    enum Corner { TopLeft, BottomRight, ... };
    enum CaseSensitivity { Insensitive, Sensitive };
    ...
};
 
tabWidget->setCornerWidget(widget, Qt::TopLeft);
str.indexOf("$(QTDIR)", Qt::Insensitive);

Что подразумевается под Insensitive в последней строке? Одно из правил задания имени значению перечисления состоит в том, чтобы в имени значения содержался хотя бы один элемент имени самого перечисления:

namespace Qt
{
    enum Corner { TopLeftCorner, BottomRightCorner, ... };
    enum CaseSensitivity { CaseInsensitive,
                           CaseSensitive };
    ...
};
 
tabWidget->setCornerWidget(widget, Qt::TopLeftCorner);
str.indexOf("$(QTDIR)", Qt::CaseInsensitive);

Когда значения перечисления могут быть использованы с оператором 'или' и как флаги, традиционным решением является сохранение результата операции 'или' в переменной типа int, который не является типобезопасным. Вместо этого Qt4 предлагает шаблон QFlags<T>, где T - тип перечисления. А для удобства в Qt есть ряд typedef'ов, так что вы можете писать Qt::Alignment вместо QFlags<Qt::AlignmentFlag>.

По соглашению мы даём имена типам в единственном числе (так как он может содержать один флаг в один момент времени), а имена флагов - во множественном числе. Например:

enum RectangleEdge { LeftEdge, RightEdge, ... };
typedef QFlags<RectangleEdge> RectangleEdges;

В некоторых случаях типы флагов имеют имена в единственном числе, а имена типов имеют приставку Flag:

enum AlignmentFlag { AlignLeft, AlignTop, ... };
typedef QFlags<AlignmentFlag> Alignment;

[править] Имена функций и параметров

Первое правило в при задании имени функции: из имени функции должно быть ясно, имеет ли она побочные эффекты. В Qt3, константная функция QString::simplifyWhiteSpace() нарушает это правило, так как она возвращает QString вместо того, чтобы модифицировать строку, для которой она вызывается (как предполагается, исходя из имени). В Qt4 эта функция переименована в QString::simplified().

Имена параметров являются важным источником информации для программиста, даже если он не видит кода, который использует API. Так как современные IDE показывают названия параметров функций, хорошей мыслью будет задать внятные имена параметрам в заголовочных файлах и использовать эти имена в документации.

[править] Имена булевых геттеров, сеттеров, и свойств

Поиск хороших имен для геттера и сеттера булевого параметра особо тяжелое занятие. Должен ли геттер называться checked() или isChecked()? scrollBarsEnabled() или areScrollBarEnabled()?

В Qt4 мы следуем следующим правилам, присваивая имя геттерам:

• К прилагательным добавляется приставка is-. Например:
  • isChecked()
  • isDown()
  • isEmpty()
  • isMovingEnabled()

• Хотя прилагательные, относящиеся к существительному во множественном числе, остаются неизменны:
  • scrollBarsEnabled(), вместо areScrollBarsEnabled()

• Глаголы не имеют приставок и не используется третье лицо (-s):
  • acceptDrops(), вместо acceptsDrops()
  • allColumnsShowFocus()

• Существительные в основном не имеют приставок:
  • autoCompletion(), вместо isAutoCompletion()
  • boundaryChecking()

• Иногда, отсутствие приставки вводит в заблуждение, тогда мы используем приставку is-:
  • isOpenGLAvailable(), вместо openGL()
  • isDialog(), вместо dialog()
    (От функции dialog(), мы обычно ожидаем, что она вернет QDialog*.)

Название сеттера получается из имени геттера, путем замены приставки is на set, например, setDown() и setScrollBarsEnabled(). Имена свойств определяются подобно именам геттеров, но без приставки is.

[править] Указатели или ссылки?

Что лучше для выходных параметров, указатели или ссылки?

void getHsv(int *h, int *s, int *v) const
void getHsv(int &h, int &s, int &v) const

Большинство книг по C++ рекомендуют использовать ссылки, где это возможно, исходя из того, что ссылки "безопаснее и красивее" указателей. В противоположность этому, в Trolltech, мы, как правило, предпочитаем указатели, поскольку они делают код более наглядным. Сравните:

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

Только по первой строке можно понять, что с большой вероятностью h, s и v будут модифицированы в методе getHsv().

[править] Наглядный пример: QProgressBar

Чтобы продемонстрировать некоторые принципы на практике, мы рассмотрим API класса QProgressBar в Qt3 и сравним с API Qt4. В Qt3:

class QProgressBar : public QWidget
{
    ...
public:
    int totalSteps() const;
    int progress() const;
 
    const QString &progressString() const;
    bool percentageVisible() const;
    void setPercentageVisible(bool);
 
    void setCenterIndicator(bool on);
    bool centerIndicator() const;
 
    void setIndicatorFollowsStyle(bool);
    bool indicatorFollowsStyle() const;
 
public slots:
    void reset();
    virtual void setTotalSteps(int totalSteps);
    virtual void setProgress(int progress);
    void setProgress(int progress, int totalSteps);
 
protected:
    virtual bool setIndicator(QString &progressStr,
                              int progress,
                              int totalSteps);
    ...
};

API достаточно сложен и противоречив; например, из имен reset(), setTotalSteps(), и setProgress() не ясно, что они тесно связаны.

Для улучшения данного API следует сделать акцент на том, что QProgressBar похож на QAbstractSpinBox в Qt4 и его подклассы: QSpinBox, QSlider и QDial. Решение? Заменить progress и totalSteps на minimum, maximum и value. Добавить сигнал valueChanged(). Добавить вспомогательную функцию setRange().

Следующее, что обращает на себя внимание: progressString, percentage и indicator в действительности указывают на одно и то же - текст, который показывается на прогрессбаре. Обычно текстом являются проценты, но его можно заменить на что угодно при помощи setIndicator(). Вот новый API:

virtual QString text() const;
void setTextVisible(bool visible);
bool isTextVisible() const;

По умолчанию текстом является индикатор процентов, что можно изменить реализовав виртуальный метод text().

Методы setCenterIndicator() и setIndicatorFollowsStyle() в API Qt3 - это функции, которые влияют на расположение. Они удачно заменяются методом setAlignment():

void setAlignment(Qt::Alignment alignment);

Если программист не вызовет setAlignment(), то положение определится текущим стилем. Для стилей, основанных на Motif, текст будет отцентрирован; для других - с правой стороны.

Вот улучшенный API класса QProgressBar:

class QProgressBar : public QWidget
{
    ...
public:
    void setMinimum(int minimum);
    int minimum() const;
    void setMaximum(int maximum);
    int maximum() const;
    void setRange(int minimum, int maximum);
    int value() const;
 
    virtual QString text() const;
    void setTextVisible(bool visible);
    bool isTextVisible() const;
    Qt::Alignment alignment() const;
    void setAlignment(Qt::Alignment alignment);
 
public slots:
    void reset();
    void setValue(int value);
 
signals:
    void valueChanged(int value);
    ...
};

[править] Как получить правильный API

API требует тщательного продумывания. Первая версия никогда не будет правильной; вы должны тестировать его. Убедитесь, что код, использующий ваш API, читабельный.

Другой фокус заключается в том, чтобы дать кому-нибудь попробовать свой API с документацией и без нее (обзор класса и документация на методы).

Документирование также является хорошим способом для поиска имен, если вы застряли на месте: попробуйте описать элемент (класс, функцию, перечисление и т.д.) и используйте свое первое предложение как отправную точку. Если вы не можете подобрать подходящее имя, то это является сигналом того, что этот элемент не должен присутствовать в API. Если ничего не получается, но вы убеждены, что ваша концепция [API] имеет смысл, то изобретайте новое имя. Вот как были придуманы "widget", "event", "focus", и "buddy".