Редактирование: Designing Qt-Style C++ APIs

{{Панель навигации по Qt Quarterly|Выпуск 13}}
<b>от Матиаса Этриха</b>

<b>Мы закончили важное исследование в Trolltech, связанное с улучшением процесса разработки Qt. В этой статье я хочу поделиться некоторыми нашими находками и представить принципы, которые мы использовали при проектировании Qt4, а также показать вам, как использовать их в вашем коде.</b>
__TOC__
Проектирование интерфейсов программирования - сложная задача. Это такое же сложное искусство, как проектирование языков программирования. Существует множество различных принципов построения API (Application Programming Interface, интерфейс прикладного программирования), многие из которых конфликтуют друг с другом.

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

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

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



<div id="sixcharacteristicsofgoodapis"></div>
== Шесть характеристик хорошего API ==
API для программиста - это тоже самое, что и пользовательский интерфейс (GUI) для конечного пользователя. Под буквой 'P' в сокращении API имеется ввиду "Программист", не "Программа", подчеркивая тот факт, что API используются программистами (которые являются людьми).

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

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

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


<div id="theconveniencetrap"></div>

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

{{code|qt|code=
QSlider *slider = new QSlider(12, 18, 3, 13, Qt::Vertical,
                              0, "volume");
}}
намного сложнее прочитать (и даже написать), чем

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

<div id="thebooleanparametertrap"></div>

== Ловушки булевых параметров ==
Булевые параметры часто приводят к не читаемому коду. В частности, практически всегда будет ошибкой добавление <tt>булевого</tt> параметра в функцию. В Qt, традиционным примером является функция <tt>repaint()</tt>, которая принимает не обязательный <tt>булевый</tt> параметр, указывающий, олжен ли очищаться задний фон (по умолчанию) или нет. Это приводит к такому коду:
{{code|qt|code=
widget->repaint(false);
}}
который новички могут прочитать как "Не перерисовывать!"

Идея, по-видимому, состоит в том, что применение булевого параметра избавит от создания еще одной функции, что, в свою очередь, приведет к сокращению программного кода. На деле же - наоборот; сколько пользователей Qt "спиной почувствует", что делает каждая из следующих строчек? 
{{code|qt|code=
widget->repaint();
widget->repaint(true);
widget->repaint(false);
}}
Более качественный API:
{{code|qt|code=
widget->repaint();
widget->repaintWithoutErasing();
}}
В Qt4 мы решили эту проблему просто исключив возможность перерисовки без очистки виджета. Qt4 поддерживает двойную буферизацию, что делает это свойство не актуальным.

Еще ряд примеров:
{{code|qt|code=
widget->setSizePolicy(QSizePolicy::Fixed,
                      QSizePolicy::Expanding, true);
textEdit->insert("Where's Waldo?", true, true, false);
QRegExp rx("moc_*.c??", false, true);
}}
Очевидным решением является замена булевых параметров перечислениями (enum types). Так мы поступили с регистрозависимыми строками [[Qt:Документация_4.3.2/qstring | QString]]. Сравните:

{{code|qt|code=
str.replace("%USER%", user, false);               // Qt 3
str.replace("%USER%", user, Qt::CaseInsensitive); // Qt 4
}}


<div id="staticpolymorphism"></div>

== Статический полиморфизм ==
Похожие классы должны иметь схожий API. Этого можно добиться с помощью наследования, где это имеет смысл, то есть когда используется полиморфизм времени выполнения (run-time polymorphism). Но полиморфизм также имеет место быть и при проектировании. Например, если бы вы заменили QListBox на [[Qt:Документация_4.3.2/qcombobox | QComboBox]] или QSlider на [[Qt:Документация_4.3.2/qspinbox | QSpinBox]], то обнаружили бы, что похожие API способствовали более легкой замене. Вот что мы называем "статическим полиморфизмом".

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

<div id="theartofnaming"></div>

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



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

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

Другое важное, но не очевидное правило, при проектировании классов - вы должны постараться сохранить ясное пространство имен подклассов. В Qt3 не всегда следовали этому правилу. Чтобы продемонстрировать это, мы приведем в пример класс [[Qt:Документация_4.3.2/qtoolbutton | QToolButton]]. Что вы ожидаете при вызове методов <tt>name()</tt>, <tt>caption()</tt>, <tt>text()</tt> или <tt>textLabel()</tt> класса [[Qt:Документация_4.3.2/qtoolbutton | QToolButton]]? Просто попробуйте поиграть с [[Qt:Документация_4.3.2/qtoolbutton | QToolButton]] в Дизайнере форм:

* Свойство <tt>name</tt> наследуется от [[Qt:Документация_4.3.2/qobject | QObject]] и указывает на имя внутреннего объекта, которое может быть использовано для отладки и тестирования.
* Свойство <tt>caption</tt> наследуется от [[Qt:Документация_4.3.2/qwidget | QWidget]] и указывает на заголовок окна, который не имеет значения для [[Qt:Документация_4.3.2/qtoolbutton | QToolButton]], так как обычно он создается внутри родительского виджета.
* Свойство <tt>text</tt> наследуется от QButton и обычно используется на кнопке, если <tt>useTextLabel</tt> ложно.
* Свойство <tt>textLabel</tt> объявленно в [[Qt:Документация_4.3.2/qtoolbutton | QToolButton]] и отображается на кнопке, если <tt>useTextLabel</tt> истинно.

В Qt4 в интересах удобочитаемости свойство <tt>name</tt> у [[Qt:Документация_4.3.2/qtoolbutton | QToolButton]] названо <tt>objectName</tt>, свойство <tt>caption</tt> стало <tt>windowTitle</tt> и <tt>textLabel</tt> изменено на <tt>text</tt>.


=== Имена классов ===
Определите группы классов вместо того, чтобы придумывать имя для каждого отдельного класса. Например, все классы, основанные на поэлементном представлении данных, в архитектуре Модель/Представление (Model/View) имеют суффикс View ([[Qt:Документация_4.3.2/qlistview | QListView]], [[Qt:Документация_4.3.2/qtableview | QTableView]] и [[Qt:Документация_4.3.2/qtreeview | QTreeView]]), а соответствующие им виджеты имеют суффикс Widget ([[Qt:Документация_4.3.2/qlistwidget | QListWidget]], [[Qt:Документация_4.3.2/qtablewidget | QTableWidget]] и [[Qt:Документация_4.3.2/qtreewidget | QTreeWidget]]).

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

{{code|qt|code=
namespace Qt
{
    enum Corner { TopLeft, BottomRight, ... };
    enum CaseSensitivity { Insensitive, Sensitive };
    ...
};

tabWidget->setCornerWidget(widget, Qt::TopLeft);
str.indexOf("$(QTDIR)", Qt::Insensitive);
}}

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

{{code|qt|code=
namespace Qt
{
    enum Corner { TopLeftCorner, BottomRightCorner, ... };
    enum CaseSensitivity { CaseInsensitive,
                           CaseSensitive };
    ...
};

tabWidget->setCornerWidget(widget, Qt::TopLeftCorner);
str.indexOf("$(QTDIR)", Qt::CaseInsensitive);
}}

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

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

{{code|qt|code=
enum RectangleEdge { LeftEdge, RightEdge, ... };
typedef QFlags<RectangleEdge> RectangleEdges;
}}

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

{{code|qt|code=
enum AlignmentFlag { AlignLeft, AlignTop, ... };
typedef QFlags<AlignmentFlag> Alignment;
}}

=== Имена функций и параметров ===
Первое правило в при задании имени функции: из имени функции должно быть ясно, имеет ли она побочные эффекты. В Qt3, константная функция <tt>QString::simplifyWhiteSpace()</tt> нарушает это правило, так как она возвращает [[Qt:Документация_4.3.2/qstring | QString]] вместо того, чтобы модифицировать строку, для которой она вызывается (как предполагается, исходя из имени). В Qt4 эта функция переименована в <tt>QString::simplified()</tt>.

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

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

В Qt4 мы следуем следующим правилам, присваивая имя геттерам:
* К прилагательным добавляется приставка <tt>is</tt>-. Например:
** <tt>isChecked()</tt> 
** <tt>isDown()</tt> 
** <tt>isEmpty()</tt> 
** <tt>isMovingEnabled()</tt> 

*Хотя прилагательные, относящиеся к существительному во множественном числе, остаются неизменны:
** <tt>scrollBarsEnabled()</tt>, вместо <tt>'''are'''ScrollBarsEnabled()</tt> 

*Глаголы не имеют приставок и не используется третье лицо (-<tt>s</tt>):
** <tt>acceptDrops()</tt>, вместо <tt>accept'''s'''Drops()</tt> 
** <tt>allColumnsShowFocus()</tt> 

*Существительные в основном не имеют приставок:
** <tt>autoCompletion()</tt>, вместо <tt>'''is'''AutoCompletion()</tt> 
** <tt>boundaryChecking()</tt> 

* Иногда, отсутствие приставки вводит в заблуждение, тогда мы используем приставку <tt>is</tt>-:
** <tt>isOpenGLAvailable()</tt>, вместо <tt>openGL()</tt> 
** <tt>isDialog()</tt>, вместо <tt>dialog()</tt> 

*(От функции <tt>dialog()</tt>, мы обычно ожидаем, что она вернет [[Qt:Документация_4.3.2/qdialog | QDialog]] <tt>*</tt>.)

Название сеттера получается из имени геттера, путем замены приставки <tt>is</tt> на <tt>set</tt>, например, <tt>'''set'''Down()</tt> и <tt>'''set'''ScrollBarsEnabled()</tt>. Имена свойств определяются подобно именам геттеров, но без приставки <tt>is</tt>. 


<div id="pointersorreferences"></div>

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

{{code|qt|code=
void getHsv(int *h, int *s, int *v) const
void getHsv(int &h, int &s, int &v) const
}}

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

{{code|qt|code=
color.getHsv(&h, &s, &v);
color.getHsv(h, s, v);
}}

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

<div id="casestudyqprogressbar"></div>

== Наглядный пример: QProgressBar ==
Чтобы продемонстрировать некоторые принципы на практике, мы рассмотрим API класса [[Qt:Документация_4.3.2/qprogressbar | QProgressBar]] в Qt3 и сравним с API Qt4. В Qt3:

{{code|qt|code=
class QProgressBar : public QWidget
{
    ...
public:
    int totalSteps() const;
    int progress() const;

    const QString &amp;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 &amp;progressStr,
                              int progress,
                              int totalSteps);
    ...
};
}}
API достаточно сложен и противоречив; например, из имен <tt>reset()</tt>, <tt>setTotalSteps()</tt>, и <tt>setProgress()</tt> не ясно, что они тесно связаны.

Для улучшения данного API следует сделать акцент на том, что [[Qt:Документация_4.3.2/qprogressbar | QProgressBar]] похож на [[Qt:Документация_4.3.2/qabstractspinbox | QAbstractSpinBox]] в Qt4 и его подклассы: [[Qt:Документация_4.3.2/qspinbox | QSpinBox]], QSlider и [[Qt:Документация_4.3.2/qdial | QDial]]. Решение? Заменить <tt>progress</tt> и <tt>totalSteps</tt> на <tt>minimum</tt>, <tt>maximum</tt> и <tt>value</tt>. Добавить сигнал <tt>valueChanged()</tt>. Добавить вспомогательную функцию <tt>setRange()</tt>.

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

{{code|qt|code=
virtual QString text() const;
void setTextVisible(bool visible);
bool isTextVisible() const;
}}

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

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

{{code|qt|code=
void setAlignment(Qt::Alignment alignment);
}}

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

Вот улучшенный API класса [[Qt:Документация_4.3.2/qprogressbar | QProgressBar]]:

{{code|qt|code=
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);
    ...
};
}}

<div id="howtogetapisright"></div>

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

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

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