- •Оглавление
- •Об авторе
- •Благодарности
- •Предисловие
- •Глава 1. Держим оборону
- •На пути к хорошему коду
- •Готовьтесь к худшему
- •Что такое защитное программирование?
- •Этот страшный, ужасный мир
- •Технологии защитного программирования
- •Выберите хороший стиль кодирования и пользуйтесь крепкой архитектурой
- •Пишите код без спешки
- •Не верьте никому
- •Стремитесь к ясности, а не к краткости
- •Не позволяйте никому лезть туда, где ему нечего делать
- •Включайте вывод всех предупреждений при компиляции
- •Пользуйтесь средствами статического анализа
- •Применяйте безопасные структуры данных
- •Проверяйте все возвращаемые значения
- •Аккуратно обращайтесь с памятью (и другими ценными ресурсами)
- •Инициализируйте все переменные там, где вы их объявили
- •Объявляйте переменные как можно позже
- •Пользуйтесь стандартными средствами языка
- •Пользуйтесь хорошими средствами регистрации диагностических сообщений
- •Выполняйте приведение типов с осторожностью
- •Подробности
- •Ограничения
- •Какие ограничения налагать
- •Снятие ограничений
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 2. Тонкий расчет
- •Да в чем проблема?
- •Знайте своих клиентов
- •Что такое хорошее представление?
- •Размещение скобок
- •Скобки в стиле K&R
- •Расширенный стиль скобок
- •Стиль Уайтсмита (с отступами)
- •Другие стили скобок
- •Единственно верный стиль
- •Внутрифирменные стили (и когда их придерживаться)
- •Установка стандарта
- •Религиозные войны?
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 3. Что в имени тебе моем?
- •Зачем нужны хорошие имена?
- •Каким объектам мы даем имена?
- •Игра в названия
- •Описательность
- •Техническая корректность
- •Идиоматичность
- •Тактичность
- •Технические подробности
- •Имена переменных
- •Имена функций
- •Имена типов
- •Пространства имен
- •Имена макросов
- •Имена файлов
- •Роза пахнет розой
- •Соблюдайте единообразие
- •Связывайте имя с содержимым
- •Извлекайте выгоду из выбора имени
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 4. Литературоведение
- •Самодокументируемый код
- •Техника написания самодокументируемого кода
- •Пишите простой код с хорошим форматированием
- •Выбирайте осмысленные имена
- •Разбивайте код на самостоятельные функции
- •Выбирайте содержательные имена типов
- •Применяйте именованные константы
- •Выделяйте важные фрагменты кода
- •Объединяйте взаимосвязанные данные
- •Снабжайте файлы заголовками
- •Правильно обрабатывайте ошибки
- •Пишите осмысленные комментарии
- •Практические методологии самодокументирования
- •Грамотное программирование
- •Инструментарий документирования
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 5. Заметки на полях
- •Что есть комментарий в коде?
- •Как выглядят комментарии?
- •Сколько комментариев требуется?
- •Что помещать в комментарии?
- •Не нужно описывать код
- •Не подменяйте код
- •Как сделать комментарии полезными
- •Не отвлекаться
- •На практике
- •Замечание об эстетичности
- •Единообразие
- •Четкие блочные комментарии
- •Отступы в комментариях
- •Комментарии в конце строки
- •Помощь в чтении кода
- •Стиль должен обеспечивать легкость сопровождения
- •Границы
- •Флажки
- •Комментарии в заголовке файла
- •Работа с комментариями
- •Помощь при написании программ
- •Заметки об исправлении ошибок
- •Устаревание комментариев
- •Сопровождение и бессодержательные комментарии
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 6. Людям свойственно ошибаться
- •Откуда что берется
- •Механизмы сообщения об ошибках
- •Без обработки ошибок
- •Возвращаемые значения
- •Переменные, содержащие состояние ошибки
- •Исключения
- •Сигналы
- •Обнаружение ошибок
- •Обработка ошибок
- •Когда обрабатывать ошибки
- •Варианты реагирования
- •Последствия для кода
- •Подымаем скандал
- •Управление ошибками
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 7. Инструментарий программиста
- •Что такое инструмент программирования?
- •А зачем они нужны – инструменты?
- •Электроинструменты
- •Выясните, каковы его возможности
- •Научитесь им управлять
- •Выясните, для каких задач он пригоден
- •Убедитесь, что он работает
- •Имейте четкие данные о том, как получить дополнительные сведения
- •Узнайте, как получить новые версии
- •Какой инструмент необходим?
- •Средства редактирования исходного кода
- •Средства построения кода
- •Инструменты для отладки и тестирования
- •Средства поддержки языка
- •Инструменты различного назначения
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 8. Время испытаний
- •Проверка на подлинность
- •Кто, что, когда, зачем?
- •Зачем тестировать
- •Кому тестировать
- •В чем состоит тестирование
- •Когда тестировать
- •Типы тестирования
- •Выбор контрольных примеров для блочного тестирования
- •Архитектура и тестирование
- •Руками не трогать!
- •Анатомия провала
- •Справлюсь ли я сам?
- •Система контроля ошибок
- •Обсуждение ошибок
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 9. Поиск ошибок
- •Реальные факты
- •Природа этого зверя
- •Взгляд с высоты птичьего полета
- •Взгляд с поверхности земли
- •Взгляд из глубины
- •Борьба с вредителями
- •Обходная дорога
- •Правильный путь
- •Охота за ошибками
- •Ошибки этапа компиляции
- •Ошибки этапа исполнения
- •Как исправлять ошибки
- •Профилактика
- •Отладчик
- •Средство проверки доступа к памяти
- •Трассировщик системных вызовов
- •Дамп памяти
- •Журналирование
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 10. Код, который построил Джек
- •Языковые барьеры
- •Интерпретируемые языки
- •Компилируемые языки
- •Делаем слона из мухи
- •Выполнение сборки
- •Что должна уметь хорошая система сборки?
- •Простота
- •Единообразие
- •Повторяемость и надежность
- •Атомарность
- •Борьба с ошибками
- •Механика сборки
- •Выбор целей
- •Уборка
- •Зависимости
- •Автоматическая сборка
- •Конфигурация сборки
- •Рекурсивное применение make
- •Мастер на все руки
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 11. Жажда скорости
- •Что такое оптимизация?
- •От чего страдает оптимальность кода?
- •Доводы против оптимизации
- •Альтернативы
- •Нужна ли оптимизация
- •Технические подробности
- •Убедитесь, что нужна оптимизация
- •Определите самую медленную часть кода
- •Тестирование кода
- •Оптимизация кода
- •После оптимизации
- •Методы оптимизации
- •Конструктивные изменения
- •Модификация кода
- •Как писать эффективный код
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 12. Комплекс незащищенности
- •Риски
- •Наши оппоненты
- •Оправдания, оправдания
- •Ощущение незащищенности
- •Опасный проект и архитектура
- •Переполнение буфера
- •Встроенные строки запросов
- •Условия гонки
- •Целочисленное переполнение
- •Дела защитные
- •Технология установки системы
- •Технология конструирования программного обеспечения
- •Технологии реализации кода
- •Технологии процедуры
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 13. Важность проектирования
- •Программирование как конструкторская работа
- •Что нужно проектировать?
- •Хороший проект программного продукта
- •Простота
- •Элегантность
- •Модульность
- •Хорошие интерфейсы
- •Расширяемость
- •Избегайте дублирования
- •Переносимость
- •Идиоматичность
- •Документированность
- •Как проектировать код
- •Методы и процедуры проектирования
- •Инструменты проектирования
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 14. Программная архитектура
- •Что такое программная архитектура?
- •План программы
- •Точки зрения
- •Где и когда этим заниматься?
- •Для чего она применяется?
- •Компоненты и соединения
- •Какими качествами должна обладать архитектура?
- •Архитектурные стили
- •Без архитектуры
- •Многоуровневая архитектура
- •Архитектура с каналами и фильтрами
- •Архитектура клиент/сервер
- •Компонентная архитектура
- •Каркасы
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 15. Программное обеспечение – эволюция или революция?
- •Гниение программного обеспечения
- •Тревожные симптомы
- •Как развивается код?
- •Вера в невозможное
- •Как с этим бороться?
- •Как писать новый код
- •Сопровождение существующего кода
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 16. Кодеры
- •Мартышкин труд
- •Нетерпеливый
- •Кодер (Code Monkey)
- •Гуру
- •Псевдогуру
- •Высокомерный гений
- •Ковбой
- •Плановик
- •Ветеран
- •Фанатик
- •Монокультурный программист
- •Лодырь
- •Руководитель поневоле
- •Идеальный программист
- •И что из этого следует?
- •Для глупцов
- •Резюме
- •План действий
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 17. Вместе мы – сила
- •Команды – общий взгляд
- •Организация команды
- •Методы управления
- •Разделение ответственности
- •Организация и структура кода
- •Инструменты для групповой работы
- •Болезни, которым подвержены команды
- •Вавилонская башня
- •Диктатура
- •Демократия
- •Большой Каньон
- •Зыбучие пески
- •Лемминги
- •Личное мастерство и качества, необходимые для работы в команде
- •Общение
- •Скромность
- •Разрешение конфликтов
- •Обучение и приспособляемость
- •Знание пределов своих возможностей
- •Принципы групповой работы
- •Коллективное владение кодом
- •Нормы кодирования
- •Определите, что считать успехом
- •Установите ответственность
- •Избегайте истощения
- •Жизненный цикл команды
- •Создание команды
- •Рост команды
- •Групповая работа
- •Роспуск команды
- •Резюме
- •План действий
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 18. Защита исходного кода
- •Управление версиями исходного кода
- •Контроль версий
- •Контроль доступа
- •Работа с хранилищем
- •Пусть растут деревья
- •Краткая история систем контроля за исходным кодом
- •Управление конфигурацией
- •Резервное копирование
- •Выпуск исходного кода
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 19. Спецификации
- •Что же это такое, конкретно?
- •Типы спецификаций
- •Спецификация требований
- •Функциональная спецификация
- •Спецификация системной архитектуры
- •Спецификация интерфейса пользователя
- •Проектная спецификация
- •Спецификация тестирования
- •Что должны содержать спецификации?
- •Процесс составления спецификаций
- •Почему мы не пишем спецификации?
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Когда проводить рецензирование?
- •Нужно ли рецензировать
- •Какой код рецензировать
- •Проведение рецензирования кода
- •Рецензирование на собраниях
- •Интеграционное рецензирование
- •Пересмотрите свое отношение
- •Позиция автора
- •Позиция рецензента
- •Идеальный код
- •За пределами рецензирования кода
- •Резюме
- •Контрольный список
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 21. Какой длины веревочка?
- •Выстрел в темноте
- •Почему трудно делать оценки?
- •Под давлением
- •Практические способы оценки
- •Игры с планами
- •Не отставай!
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 22. Рецепт программы
- •Стили программирования
- •Структурное программирование
- •Функциональное программирование
- •Логическое программирование
- •Рецепты: как и что
- •Процессы разработки
- •Каскадная модель
- •SSADM и PRINCE
- •Создание прототипов
- •Итеративная и инкрементная разработка
- •Спиральная модель
- •Другие процессы разработки
- •Спасибо, хватит!
- •Выбор процесса
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 23. За гранью возможного
- •Программирование приложений
- •Коробочные продукты
- •Заказные приложения
- •Программирование игр
- •Системное программирование
- •Встроенное программное обеспечение
- •Программирование масштаба предприятия
- •Численное программирование
- •И что дальше?
- •Резюме
- •Контрольные вопросы
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 24. Что дальше?
- •Но что же дальше?
- •Ответы и обсуждение
- •Глава 1. Держим оборону
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 2. Тонкий расчет
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 3. Что в имени тебе моем?
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 4. Литературоведение
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 5. Заметки на полях
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 6. Людям свойственно ошибаться
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 7. Инструментарий программиста
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 8. Время испытаний
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 9. Поиск ошибок
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 10. Код, который построил Джек
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 11. Жажда скорости
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 12. Комплекс незащищенности
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 13. Важность проектирования
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 14. Программная архитектура
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 15. Программное обеспечение – эволюция или революция?
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 16. Кодеры
- •Вопросы для размышления
- •Глава 17. Вместе мы – сила
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 18. Защита исходного кода
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 19. Спецификации
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 20. Рецензия на отстрел
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 21. Какой длины веревочка?
- •Вопросы для размышления
- •Вопросы личного характера
- •Глава 22. Рецепт программы
- •Вопросы для размышления
- •Глава 23. За гранью возможного
- •Вопросы для размышления
- •Вопросы личного характера
- •Библиография
- •Алфавитный указатель
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
C |
|
E |
|
|||
|
|
X |
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
||
|
F |
|
|
|
|
|
|
t |
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
r |
|
P |
|
|
|
|
|
NOW! |
o |
||
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|||
|
|
|
|
to |
|
|
|
|
|
w Click |
|
|
|
478m |
|||||
|
|
|
|
||||||
w |
|
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
|
o |
|
. |
|
|
|
|
|
.c |
||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
df |
|
|
n |
e |
||
|
|
|
|
-xcha |
|
|
|
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
|
C |
|
E |
|
|
|||
|
|
X |
|
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
|
||
|
F |
|
|
|
|
|
|
t |
|
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
|
r |
||
P |
|
|
|
|
|
NOW! |
o |
|||
|
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|
|||
|
|
|
|
to |
|
|
|
|
|
|
Глава 19. СпецификацииClick |
|
|
|
|
|
m |
||||
|
|
|
|
|
|
|||||
w |
|
|
|
|
|
|
|
o |
|
|
|
w |
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
.c |
|
||
|
. |
|
|
|
|
|
|
|||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
|
df |
|
|
n |
e |
|
||
|
|
|
|
-x cha |
|
|
|
|
Адвокат дьявола
Спецификации обходятся дорого: чтобы читать их или писать, нужны время и труд. Они требуют лишних усилий. Так ли уж необходимы все эти документы? Да, необходимы: чтобы писать программы высокого качества, нужно собрать всю эту информа% цию и разместить ее в таком месте, откуда ее при необходимости можно извлечь. Спецификации побуждают нас следовать пра% вильной практике разработки: собирать требования, проектиро% вать и составлять план тестирования – и мы видели, как они спо% собствуют общению.
Ускоренные процедуры (см. раздел «Методологии ускоренной разработки» на стр. 547) уделяют значительно меньше внимания составлению спецификаций, но они не поощряют писать код как бог на душу положит. Поскольку спецификации не пишутся са% ми по себе, легко устаревают и требуют сопровождения, а у про% граммистов и без того работы хватает, разумно писать только са% мые необходимые документы. Нужно всегда избегать долгих про% цедурных барьеров. Но любую спецификацию, от которой вы от# казались, нужно заменить равноценным объемом информации. Не пренебрегайте спецификациями, если вы не заменили их до% кументами равного качества, содержащими ту же информацию.
Вэкстремальном программировании не пишут длинные специ% фикации требований, но все требования фиксируются в эквива% лентных историях пользователя (user story), хранящихся на
карточках историй. Проектных спецификаций избегают: код является собственной документацией.
Вускоренной разработке также практикуется проектирование, управляемое тестированием, когда кодифицированные тесты выступают в качестве дополнительной документации по коду и его поведению. Такой полный и понятный набор тестов для бло% ков может заменить спецификацию тестирования для отдельных компонент, но редко подходит для проверки пригодности конеч% ного продукта.
Что должны содержать спецификации?
Разные типы спецификаций весьма различаются по содержанию. Од% нако в любой спецификации в отношении информации должны соблю% даться следующие требования:
Корректность
Несмотря на очевидность, это крайне важное требование. Некор% ректная спецификация может стать причиной многих дней напрас%
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
|
C |
|
E |
|
|
|||
|
|
X |
|
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
|
||
|
F |
|
|
|
|
|
|
t |
|
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
|
r |
|
|
P |
|
|
|
|
|
NOW! |
o |
|
||
|
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|
|||
|
|
|
|
to |
|
|
|
|
|
|
w Click |
|
|
|
Чтоm |
должны содержать спецификации? |
|||||
|
|
|
|
|||||||
w |
|
|
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
|
o |
|
|
. |
|
|
|
|
|
.c |
|
||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
|
df |
|
|
n |
e |
|
||
|
|
|
|
-xcha |
|
|
|
|
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
|
C |
|
E |
|
|
|||
|
|
X |
|
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
|
||
|
F |
|
|
|
|
|
|
t |
|
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
|
r |
||
P |
|
|
|
|
|
NOW! |
o |
|||
|
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|
|||
|
|
|
|
to |
|
|
|
|
|
|
479Click |
|
|
|
|
|
m |
||||
|
|
|
|
|
|
|||||
w |
|
|
|
|
|
|
|
o |
|
|
|
w |
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
.c |
|
||
|
. |
|
|
|
|
|
|
|||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
|
df |
|
|
n |
e |
|
||
|
|
|
|
-x cha |
|
|
|
|
ного труда. Необходимо ее постоянно обновлять, иначе она стано% вится опасной: ее чтение оказывается потерянным временем, при% водит к путанице и может стать причиной появления ошибок.
Если спецификация допускает неоднозначное толкование, это не спецификация. Два человека, прочтя ее, сделают разные выводы, что неизбежно приведет к печальным последствиям. Сделайте так, чтобы ваши спецификации точно передавали ваш замысел.
В тексте не должно быть противоречий. Если спецификация оказы% вается достаточно объемистой, соблюсти ее непротиворечивость ста% новится затруднительно. Такая проблема особенно характерна для случаев, когда модификацию проводит сопровождающий (не автор кода) – легко, изменив информацию в одном месте, оставить в преж% нем виде другие разделы, ссылающиеся на те же самые данные.
Спецификация должна быть составлена в соответствии с сущест% вующими стандартами (например, определениями языка и приня% тыми в фирме стандартами кодирования). Она должна следовать принятым в фирме стандартам/соглашениям для документов и ис% пользовать существующие шаблоны.
Понятность
Хорошую спецификацию приятно читать и легко понимать. Она понятна всякому, кто ее прочтет. Если она составлена настолько техническим языком, что разобраться в ней могут только инжене% ры, то прочие нетехнические службы (маркетинга или администра% ции) сочтут, что этот документ написан не для них, и не отнесутся к нему с должным вниманием. Возможные проблемы будут обнару% жены слишком поздно.
Как и хороший код, лучшие спецификации пишутся с точки зре% ния читателя, а не писателя. Информация представляется так, что% бы быть понятной новичку, а не в удобном для автора виде. Блез Паскаль как%то извинялся: «Это письмо получилось у меня слиш% ком долгим, потому что у меня не было времени его укоротить». Для хорошего стиля характерны краткость и очевидность главного смысла, не затененного многословием. Для этого требуются лиш% ние время и труд, но оно того стоит, если в результате достигается простота изложения.
Не нужно думать, что спецификация должна содержать массу скуч% ной прозы. Попробуйте применить приемы, сокращающие объем и облегчающие чтение. Маркированные и нумерованные списки, графики, заголовки и подзаголовки, таблицы и разумное использо% вание пустого пространства позволяют разбить поток текста и по% мочь читателю составить мысленную карту материала.
Полнота
Спецификация должна быть самодостаточной и полной. Это не озна% чает, что в ней должна содержаться вся мыслимая информация;
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
C |
|
E |
|
|||
|
|
X |
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
||
|
F |
|
|
|
|
|
|
t |
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
r |
|
P |
|
|
|
|
|
NOW! |
o |
||
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|||
|
|
|
|
to |
|
|
|
|
|
w Click |
|
|
|
480m |
|||||
|
|
|
|
||||||
w |
|
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
|
o |
|
. |
|
|
|
|
|
.c |
||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
df |
|
|
n |
e |
||
|
|
|
|
-xcha |
|
|
|
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
|
C |
|
E |
|
|
|||
|
|
X |
|
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
|
||
|
F |
|
|
|
|
|
|
t |
|
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
|
r |
||
P |
|
|
|
|
|
NOW! |
o |
|||
|
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|
|||
|
|
|
|
to |
|
|
|
|
|
|
Глава 19. СпецификацииClick |
|
|
|
|
|
m |
||||
|
|
|
|
|
|
|||||
w |
|
|
|
|
|
|
|
o |
|
|
|
w |
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
.c |
|
||
|
. |
|
|
|
|
|
|
|||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
|
df |
|
|
n |
e |
|
||
|
|
|
|
-x cha |
|
|
|
|
вполне допустимо ссылаться на относящиеся к делу документы, ес% ли эти ссылки точны (учитывайте в них версии документов) и по% зволяют читателю легко найти нужный документ.
Уровень детализации в спецификациях не должен опускаться до де% талей реализации, иначе она станет слишком ограничительной или трудной для понимания. Люди склонны игнорировать сложные спе% цификации, а потому они оказываются невостребованными. Остав% шись пылиться в углу, они только вводят в заблуждение тех читате% лей, которые не знают, что ими больше не руководствуются.
Проверяемость
Спецификация интерфейса программной компоненты приводит к по% явлению двух вещей: программной реализации и комплекта тестов для ее проверки. Поэтому содержание спецификации должно под% даваться проверке. На практике это сводится в основном к ее кор% ректности, однозначности и полноте.
Модифицируемость
Ничто не должно устанавливаться навечно – ни код, ни документы. Если спецификация требует обновления (например, для исправле% ния фактической ошибки), это не должно вызывать затруднений. Жесткая спецификация помогает вам обрести почву под ногами. Но если спецификация неверна, в этом нет никакого смысла. Доку% мент должен быть доступен для редактирования (т. е. должен быть обеспечен доступ к источнику, а не просто экземпляру в формате PDF), а процедура выпуска и обновления не должна быть слишком обременительной.
Чтобы облегчить модификации, документ должен быть тщательно структурирован и иметь минимальный размер.
Самоописательность
В каждой спецификации должны присутствовать как минимум следующие части:
•Форзац, ясно показывающий название документа, подзаголо% вок, авторов, номер версии, дату последней модификации и ста% тус доступа (например, закрытый документ компании, распро% странение на условиях NDA, открытый доступ).
•Введение, содержащее краткие сведения о задачах, области при% менения и предполагаемой аудитории.
•Термины и определения, необходимые для понимания содержи% мого. (Но не относитесь к читателю свысока: если документ предназначен инженерам%программистам, не нужно объяснять им, что такое RAM.)
•Ссылки на аналогичные или цитируемые документы.
•Исторический раздел, перечисляющий важные модификации и версии.
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
|
C |
|
E |
|
|
|||
|
|
X |
|
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
|
||
|
F |
|
|
|
|
|
|
t |
|
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
|
r |
|
|
P |
|
|
|
|
|
NOW! |
o |
|
||
|
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|
|||
|
|
|
|
to |
|
|
|
|
|
|
w Click |
|
|
|
Процессm |
составления спецификаций |
|||||
|
|
|
|
|||||||
w |
|
|
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
|
o |
|
|
. |
|
|
|
|
|
.c |
|
||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
|
df |
|
|
n |
e |
|
||
|
|
|
|
-xcha |
|
|
|
|
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
|
C |
|
E |
|
|
|||
|
|
X |
|
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
|
||
|
F |
|
|
|
|
|
|
t |
|
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
|
r |
||
P |
|
|
|
|
|
NOW! |
o |
|||
|
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|
|||
|
|
|
|
to |
|
|
|
|
|
|
481Click |
|
|
|
|
|
m |
||||
|
|
|
|
|
|
|||||
w |
|
|
|
|
|
|
|
o |
|
|
|
w |
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
.c |
|
||
|
. |
|
|
|
|
|
|
|||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
|
df |
|
|
n |
e |
|
||
|
|
|
|
-x cha |
|
|
|
|
Прослеживаемость
Должна существовать процедура контроля за документами (типа системы управления исходным кодом) и центральное файловое хранилище документов. Каждая выпускаемая версия специфика% ции должна помещаться в хранилище и оставаться доступной, что% бы можно было узнать, с какой версией вы работали год назад; в один прекрасный день она вам снова понадобится. Можно вос% пользоваться системой управления версиями – этот инструмент го% дится для отслеживания версий файлов любого типа.
На форзаце документа имеется контрольная информация (номер версии, дата, автор и т. д.), которая позволяет убедиться, что у вас на руках самый свежий экземпляр.
Составляя спецификацию, обдумайте ее содержание. Выберите структуру и словарь, понятные аудитории, и убедитесь, что документ корректен, по& лон и содержит собственное описание.
Процесс составления спецификаций
То, что написано без усилий, обычно читается без удовольствия.
Сэмюэл Джонсон
Теперь, когда мы знаем, какие типы спецификаций существуют и что они должны содержать, мы полностью вооружены. Пора что%нибудь написать! Процесс составления спецификации прост:
1.Выберите начальный шаблон документа. Он может быть определен установленной процедурой разработки проекта. Если шаблона нет, возьмите за основу существующую спецификацию.
2.Напишите документ. Действительно, это трудная часть. Что пи% сать, зависит от типа спецификации.
3.Организуйте обсуждение документа. Привлеките всех, кому он мо% жет быть интересен.
4.После согласования (и, если требует процедура, официального под% писания) присвойте документу номер версии, поместите в хранили% ще и разошлите соответствующим адресатам.
5.Если в дальнейшем возникнут проблемы, сделайте заявку на изме% нение спецификации и проверьте, что вам ясно, как модификация повлияет на объем работы по разработке. Если не ясно, то объем ра% бот может совершенно незаметно удвоиться.
Написать этот список нетрудно – трудно выполнить. Можно сосредо% точить усилия на пункте 2 и опустить остальные, чтобы облегчить себе жизнь. Но без прочих действий вы не сможете создать официальный, опознаваемый документ; впоследствии это может создать проблемы.
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
C |
|
E |
|
|||
|
|
X |
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
||
|
F |
|
|
|
|
|
|
t |
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
r |
|
P |
|
|
|
|
|
NOW! |
o |
||
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|||
|
|
|
|
to |
|
|
|
|
|
w Click |
|
|
|
482m |
|||||
|
|
|
|
||||||
w |
|
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
|
o |
|
. |
|
|
|
|
|
.c |
||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
df |
|
|
n |
e |
||
|
|
|
|
-xcha |
|
|
|
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
|
C |
|
E |
|
|
|||
|
|
X |
|
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
|
||
|
F |
|
|
|
|
|
|
t |
|
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
|
r |
||
P |
|
|
|
|
|
NOW! |
o |
|||
|
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|
|||
|
|
|
|
to |
|
|
|
|
|
|
Глава 19. СпецификацииClick |
|
|
|
|
|
m |
||||
|
|
|
|
|
|
|||||
w |
|
|
|
|
|
|
|
o |
|
|
|
w |
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
.c |
|
||
|
. |
|
|
|
|
|
|
|||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
|
df |
|
|
n |
e |
|
||
|
|
|
|
-x cha |
|
|
|
|
Создавая свой литературный шедевр, воспользуйтесь следующими ре% комендациями. Первые из них относятся к авторству и вашим эстети% ческим пристрастиям:
•Обычно тексты лучше удаются, когда у каждого документа один ав% тор. Координировать несколько авторов и согласовывать разные стили бывает трудно. Если вы пишете документацию для большой системы, разбейте спецификацию на части, и пусть над каждой ча% стью работает один человек. Создайте общий документ, который свяжет вместе все части.
Вопреки некоторым мнениям, нет ничего нескромного в том, что на обложке спецификации красуется одна фамилия. Должен же кто%то отвечать за этот документ своей репутацией – и когда автор достоин похвалы, и когда заслуживает порицания!
Если вы существенно развили документ, написанный кем%то другим, не стесняйтесь добавить свое имя к списку авторов. Но никого не уда% ляйте из этого списка, если только не убрана написанная им часть.
•Автора нужно подбирать правильно. Служба маркетинга не напи% шет вам функциональные спецификации; она снабжает вас требо% ваниями. Менеджеры не проектируют код; это делает разработчик, у которого есть соответствующие знания и умение. Автор должен уметь писать – это мастерство, которым можно овладеть, мускул, требующий упражнений.
•Для каждого документа должен быть определен владелец, который несет за него ответственность. Владелец может не быть автором пер% воначальной версии; это может быть технический руководитель или лицо, сопровождающее документ, если его автор более недоступен.
Вот несколько советов по написанию документа:
•Полезно иметь хорошие конкретные примеры спецификаций каж% дого вида. По ним автор может определить, чего от него ждут.
•Если спецификация носит предварительный характер, она должна быть помечена соответствующим образом и содержать предупреж% дение, что данный вариант не является окончательным. Это защи% тит людей от ошибочного восприятия спецификации как готовой, а вас – от их жалоб на качество (временно). Ведите список незавер% шенных разделов и открытых проблем внутри самого документа.
•Важно рецензировать документ; это способствует его корректности и правильному представлению. Рецензирование служит средством получить согласие других лиц с вашими решениями и тем самым придать авторитетность вашему документу. Особенно это необходи% мо для спецификаций, направляемых вне проекта – заказчику или в другие подразделения.
•Завершив разработку спецификации, не забывайте про нее. Она
должна работать и своевременно обновляться. Функциональная
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
|
C |
|
E |
|
|
|||
|
|
X |
|
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
|
||
|
F |
|
|
|
|
|
|
t |
|
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
|
r |
|
|
P |
|
|
|
|
|
NOW! |
o |
|
||
|
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|
|||
|
|
|
|
to |
|
|
|
|
|
|
w Click |
|
|
|
Процессm |
составления спецификаций |
|||||
|
|
|
|
|||||||
w |
|
|
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
|
o |
|
|
. |
|
|
|
|
|
.c |
|
||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
|
df |
|
|
n |
e |
|
||
|
|
|
|
-xcha |
|
|
|
|
|
|
|
|
hang |
e |
|
|
|
|
|
|
|
|
C |
|
E |
|
|
|||
|
|
X |
|
|
|
|
|
|||
|
- |
|
|
|
|
|
d |
|
||
|
F |
|
|
|
|
|
|
t |
|
|
|
D |
|
|
|
|
|
|
|
i |
|
|
|
|
|
|
|
|
|
r |
||
P |
|
|
|
|
|
NOW! |
o |
|||
|
|
|
|
|
|
|
||||
|
|
|
|
|
BUY |
|
|
|||
|
|
|
|
to |
|
|
|
|
|
|
483Click |
|
|
|
|
|
m |
||||
|
|
|
|
|
|
|||||
w |
|
|
|
|
|
|
|
o |
|
|
|
w |
|
|
|
|
|
|
|
|
|
w |
|
|
|
|
|
|
.c |
|
||
|
. |
|
|
|
|
|
|
|||
|
|
p |
|
|
|
|
g |
|
|
|
|
|
|
df |
|
|
n |
e |
|
||
|
|
|
|
-x cha |
|
|
|
|
спецификация не кончается с завершением этапа проектирования. Требования претерпевают изменения, и мы получаем новые данные о функционировании системы. Все это нужно отражать в новых версиях спецификаций.
Языковые барьеры
Ненавижу определения.
Бенжамин Дизраэли
Очень внимательно пишите текст спецификации. По сравнению с кодом английский язык полон двусмысленностей и сложностей. По газетным заголовкам особенно хорошо видно, насколько неод% нозначными бывают простые английские предложения: «Stolen painting found by tree», «Kids make nutritious snacks», «Red tape holds up new bridge» и «Hospitals are sued by 7 foot doctors».
Спецификации – официальные документы, они не должны быть многословными или написанными разговорным стилем; это скрыло бы за словами важные факты. У читателей, для которых английский не является родным языком, могут возникнуть трудности. Однако слишком сжатый документ тяжело воспри% нимается. Необходимо соблюдать меру, и рецензирование доку% мента поможет выбрать правильный стиль письма.
Официальные документы пишутся от третьего лица, в настоя% щем времени. Очень важно тщательно подбирать слова. Полез% ное соглашение содержится в RFC 2119. Там определены сле% дующие ключевые термины для спецификаций протоколов (они очень полезны и в спецификациях требований):
Must (Должен)
Слово must (или shall, или is required to) означает, что сле% дующее определение является безусловным требованием спе% цификации.
Must not (Не должен)
Слова must not (или shall not) означают безусловное запреще% ние спецификации.
Should (Следует)
Пользуйтесь should (или recommended, рекомендуется) для обозначения необязательного требования – поведения, кото% рое можно игнорировать, но только если понятны и учтены все возможные последствия.