Эндрю Хант - Программист-прагматик. Путь от подмастерья к мастеру

Если дефект проскальзывает через сеть существующих тестов, вам необходимо добавить новый тест, чтобы поймать его в следующий раз.

Подсказка 66: Дефект должен обнаруживаться единожды

Если тестировщик обнаруживает дефект, это должно быть в первый и последний раз – обнаружение дефекта человеком. Автоматизированные тесты должны быть модифицированы для проверки наличия этого дефекта, начиная с момента его первоначального обнаружения, всякий раз, без каких-либо исключений, не обращая внимания на степень тривиальности, жалобы разработчика и его фразу «Этого больше не случится».

Потому что это снова случится. А у нас просто нет времени гоняться за дефектами, которые автоматизированные тесты не могли обнаружить. И нам придется тратить время на написание новой программы – с новыми дефектами.

• Мой исходный текст съел кот Мурзик

• Отладка

• Несвязанность и закон Деметера

• Реорганизация

• Программа, которую легко тестировать

• Вездесущая автоматизация

• Можете ли вы осуществить автоматическое тестирование вашего проекта? Многие команды вынуждены дать отрицательный ответ. Почему? Слишком сложно определить приемлемые результаты? Не приведет ли к затруднениям попытка доказать спонсорам, что проект «сделан»?

Сложно ли проверить логику приложения независимо от графического интерфейса? Что можно сказать о графическом интерфейсе? О связывании?

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

Прагматики воспринимают документацию как неотъемлемую часть общего процесса разработки. Написание документации может быть облегчено, если вы не дублируете усилия, не теряете времени попусту и держите документацию под рукой, а если это возможно, – то в самой программе.

Эти мысли не отличаются оригинальностью и новизной; идея о брачном союзе программы и документации к ней появляется уже в работе Доналда Кнута о грамотном программировании и в утилите JavaDoc фирмы Sun. Мы хотим уменьшить противоречие между программой и документацией и вместо этого считать их двумя визуальными представлениями одной и той же модели (см. «Всего лишь визуальное представление»). На самом деле мы хотим пойти немножко дальше и применить все наши прагматические принципы к документации так, как мы применяем их к программам.

Подсказка 67: Считайте естественный язык одним из языков программирования

Существует два основных вида документации, которая готовится для проекта: внутренняя и внешняя. Внутренняя документация включает комментарии исходных текстов, документы, касающиеся проектирования и тестирования, и т. д. Внешняя документация – это то, что отправляется заказчику или публикуется для внешнего мира, например, руководство пользователя. Но вне зависимости от целевой аудитории или роли автора (разработчик он или технический писатель), вся документация является отражением программы. При наличии несоответствий программа – это то, что имеет значение.

Подсказка 68: Встраивайте документацию в проект, а не накручивайте ее сверху

Начнем с внутренней документации.

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

В общем, комментарии должны обсуждать, почему выполняется та или иная операция, ее задачу и ее цель. Программа всегда демонстрирует, как это делается, поэтому комментирование – избыточная информация и нарушение принципа DRY.

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

Мы предпочитаем увидеть простой комментарий в заголовке (на уровне модуля), комментарии к существенным данным и объявлениям типов и краткие заголовки для каждого из классов и методов, описывающие, как используется именно эта функция и все ее неочевидные действия.