Печатать документ или ткать его на холсте?

Издаваемой бумажной документации присуща одна проблема: она может устареть, пока будет напечатана. Документация в любой ее форме – лишь моментальный снимок.

Поэтому мы стараемся создавать всю документацию в форме, которая может быть помещена в информационную сеть, на web-страницу вместе с гиперссылками. Такое представление документации легче сохранять в обновленном виде, чем отслеживать все существующие бумажные экземпляры, уничтожать их и распространять обновленные версии. Это также является лучшим способом обращения к нуждам широкой аудитории. Однако не забывайте помещать дату или номер версии на каждой web-странице. В этом случае читатель сможет разобраться, что соответствует текущему моменту, что изменилось недавно, а что осталось неизменным.

Во многих случаях вам приходится представлять одну и ту же документацию в различных форматах: в печатном, в виде web-страницы, экранной справки, а может быть, и как слайд-шоу. Обычное решение в большой степени полагается на технологию "вырезать и вставить" на и создание нескольких независимых документов из одного оригинала. Это неудачная идея: представление документа не должно зависеть от его содержания.

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

<H1>Chapter Title</Н1>

для генерации новой главы в отчетной версии документа и названия нового слайда в слайд-шоу. Можно воспользоваться технологиями типа XSL и CSS [54] для генерирования множественных выходных форматов из этого описания.

Если вы используете текстовый процессор, то, по всей вероятности, будете располагать аналогичными возможностями. Если не забывали использовать стили для идентификации различных элементов документа, то, применяя различные таблицы стилей, вы можете существенным образом изменить внешний вид окончательного результата. Большинство современных текстовых процессоров позволяет конвертировать документы в форматы типа HTML для публикации на web-сайтах.

Языки разметки

Мы рекомендуем рассмотреть некоторые из современных схем описания документации для крупномасштабных проектов по документированию.

Многие авторы, пишущие на технические темы, используют в настоящее время средство DocBook для описания своих документов. DocBook представляет собой стандарт описания документов на основе SGML, который тщательно идентифицирует каждый компонент в документе. Документ можно обрабатывать процессором DSSSL для его преобразования в любое число различных форматов. Проект документации Linux использует DocBook для представления информации в форматах RTF, ТеХ, info, PostScript и HTML.

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

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

Другие разделы, относящиеся к данной теме:

• Пороки дублирования

• Ортогональность

• Преимущества простого текста

• Управление исходным текстом

• Всего лишь визуальное представление

• Программирование в расчете на стечение обстоятельств

• Карьер для добычи требований

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

Вопросы для обсуждения

• Приходилось ли вам писать пояснительный комментарий для исходного текста программы, который вы только записали? Почему нет? Не было времени? Не уверены, что программа действительно работает – пробуете некую идею в виде прототипа? Впоследствии вы выбросите эту программу, не правда ли? Ведь при этом она не попадет в проект без комментариев и в экспериментальном виде, не так ли?

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

Большие надежды

Подивитесь сему, небеса, и содрогнитесь, и ужаснитесь, говорит Господь.

Иеремия (2,12)

Компания объявляет о рекордной прибыли, а цена на ее акции падает на 20 %. Вечерняя телепрограмма финансовых новостей объясняет, что компании не удалось оправдать надежды аналитиков. Ребенок открывает дорогой рождественский подарок – и в слезы: там нет дешевой куклы, на которую он так надеялся. Проектная команда творит чудеса, реализуя феноменально сложное приложение, и лишь для того, чтобы получить ушат воды со стороны пользователей, поскольку в системе отсутствует справка.

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

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

Подсказка 69: Слегка превышайте надежды ваших пользователей

Однако выполнение этой подсказки требует некоторых усилий.

Передача надежд

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

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

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

Существует ряд методик, которые могут использоваться для облегчения этого процесса. Из них наиболее важными являются "Стрельба трассирующими" и "Прототипы и памятные записки". Обе методики позволяют команде конструировать то, что может увидеть пользователь. Обе являются идеальными способами передать ваше понимание требований пользователей, обедают возможность вам и вашим пользователям практиковаться в общении друг с другом.

Небольшой довесок

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

ЭТО ПЛОХО. Постарайтесь удивить ваших пользователей. Заметьте, их не надо пугать, их надо восхищать.

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

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

• Всплывающая подсказка

• «Горячие» комбинации клавиш

• Краткое справочное руководство в качестве дополнения к руководству пользователя

• Расцвечивание

• Анализаторы журнала регистрации

• Автоматическая инсталляция

• Инструментальные средства проверки целостности системы

• Возможность запускать несколько версий системы в целях тренировки

• Экран-заставка, настроенный для фирмы-заказчика

Все эти вещи относительно поверхностны и особо не нагружают систему. Однако каждый из этих «довесков» говорит пользователям о том, что команда разработчиков позаботилась о создании отличной системы, предназначенной для использования в реальной жизни. Просто не забывайте о том, что работа системы не должна быть расстроена этими нововведениями.

Другие разделы, относящиеся к данной теме:

• Неплохие программы

• Стрельба трассирующими

• Прототипы и памятные записки

• Карьер для добычи требований

Вопросы для обсуждения

• Иногда самыми жесткими критиками проекта являются те, кто над ним работал. Случалось ли вам испытывать разочарование, когда ваши собственные надежды не были оправданы тем, что вы создали? Как это могло произойти? Может быть здесь присутствует нечто большее, чем логика.

• Что говорят ваши пользователи, когда вы поставляете им готовую программу? Пропорционально ли их внимание к различным аспектам данной программы усилиям, которые вы в эти аспекты вложили? Что их восхищает?

Гордость и предубеждение

Вы восхищали нас довольно долго.

Джейн Остин, Гордость и предубеждение

Программисты-прагматики не уклоняются от ответственности. Вместо этого они испытывают радость, принимая вызовы и распространяя свой опыт. Если мы несем ответственность за проектное решение или фрагмент программы, мы делаем работу, которой можем гордиться.

Подсказка 70: Ставьте вашу подпись под работой

В прошлом мастеровые гордились, подписывая свою работу. Вы должны следовать их примеру.

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

Этого-то мы и не хотим. Вы не должны ревниво защищать свою программу от тех, кто вторгается в ее пределы; вы должны платить людям той же монетой и относиться к программам других разработчиков с уважением. Золотое правило ("Поступай с другими так, как бы ты хотел, чтобы они поступали с тобой") и взаимоуважение среди разработчиков является важным для действия подсказки, приведенной выше.

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

У программы должен быть владелец, но он не обязательно является физическим лицом. Успешный метод eXtreme Programming [URL 45], разработанный Кентом Беком, рекомендует коллективную собственность на программу (но это требует дополнительных процедур типа парного программирования в целях защиты от анонимности).

Мы хотим, чтобы вы гордились правом собственности. "Я это написал, и я стою за своей работой". Ваша подпись должна стать признанным знаком качества. Люди должны увидеть ваше имя в заголовке программы и рассчитывать на то, что она будет солидной, хорошо составленной, проверенной и документированной. Эта должна быть поистине профессиональная работа. Написанная настоящим профессионалом.

Прагматиком-программистом.

Приложение А

Информационные ресурсы

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

Книга начинается с утверждения, что программисты-прагматики должны постоянно учиться. В данном приложении приводится перечень источников информации, которые могут им в этом поспособствовать.

В разделе "Профессиональные общества" приведены координаты IEEE (Institute of Electrical and Electronical Engineers – Институт инженеров по электротехнике и радиоэлектронике) и ACM (Association of Computing Machinery – Ассоциация по вычислительной технике). Мы рекомендуем программисту-прагматику вступить в ряды одного (или обоих) из этих обществ. Ниже в разделе "Собираем библиотеку" указаны периодические издания, книги и интернет-сайты, которые содержат высококачественную и ценную информацию (или просто-напросто забавны по своему содержанию).

В книге содержится много ссылок на программные ресурсы, доступные через Интернет. В разделе «Интернет-ресурсы» приводятся их адреса (URL) с кратким описанием. Но в силу природы Интернета многие из этих адресов могут устареть к моменту выхода книги в свет. Для того чтобы найти более свежие ссылки, можно воспользоваться одной из поисковых систем или же посетить наш интернет-сайт: www.pragmaticprogrammer.com и просмотреть соответствующий раздел.

И наконец, в приложении содержится библиографический список.

Профессиональные общества

У программистов существует два профессиональных объединения мирового уровня. Association of Computing Machinery – ACM [55] (Ассоциация по вычислительной технике) и Institute of Electrical and Electronical Engineers – IEEE [56] (Компьютерное общество института инженеров по электротехнике и радиоэлектронике). Всем программистам рекомендуется вступить в одно (или оба) из этих обществ. Кроме того, разработчики, проживающие вне США, могут вступить в соответствующие национальные объединения (примером может служить British Computer Society – BCS – Британское компьютерное общество).

Члены профессиональных обществ пользуются рядом преимуществ. Конференции и собрания дают возможность общения людям с общими интересами, а специальные секции и технические комитеты позволяют участвовать в выработке стандартов и рекомендаций, используемых во всем мире. Многое можно почерпнуть из их публикаций, в которых ведутся «высоколобые» дискуссии по практическим вопросам и «приземленные» разговоры по компьютерной теории.

Собираем библиотеку

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

Периодические издания

Люди, подобные авторам книги, хранят старые журналы и периодику до тех пор, пока вес стопки не будет достаточен для превращения нижних экземпляров в алмаз. Вот некоторые периодические издания, рекомендуемые авторами.

• IEEE Computer. Рассылается по подписке членам Компьютерного общества Института инженеров по электротехнике и радиоэлектронике. Этот журнал сосредоточен на практических аспектах, но не чужд и теории. Некоторые номера посвящены конкретной тематике, другие же представляют собой просто сборники интересных статей. Говоря языком связистов, журнал обладает хорошим соотношением "сигнал-шум".

• IEEE Software. Не менее ценная публикация Компьютерного общества Института инженеров по электротехнике и радиоэлектронике, издаваемая раз в два месяца и нацеленная на программистов-практиков.

• Communications of the ACM. Основной журнал, получаемый всеми членами Ассоциации по вычислительной технике; на протяжении десятилетий является отраслевым стандартом и опубликовал больше основополагающих статей, чем любой другой источник.

• SIGPLAIM. Журнал выпускается секцией языков программирования, входящей в ассоциацию АСМ, распространяется среди членов АСМ. В нем часто публикуются спецификации языков программирования, наряду с тематическими статьями для всех, кто любит "копать вглубь".

• Dr. Dobbs Journal. Ежемесячный журнал, распространяемый по подписке и продающийся в киосках. Этот журнал непрост для восприятия, но его статьи охватывают как практические аспекты, так и чистую теорию.

• The Perl Journal. Поклонникам Perl стоит подписаться на этот журнал (www.tpj.com).

• Software Development Magazine. Ежемесячный журнал, посвященный общим вопросам управления проектами и разработки программного обеспечения.

Еженедельные профессиональные издания

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

Книги

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

Анализ и проектирование

• Object-Oriented Software Construction, второе издание. Эпическое произведение Бертрана Мейера, посвященное основам объектно-ориентированного программирования, общим объемом 1300 страниц [Меу97Ь].

• Design Patterns. Конструктивный шаблон описывает метод решения конкретного класса задач на более высоком уровне по сравнению с фразеологизмом на языке программирования. Эта неоклассическая книга [GHJV95], написанная "бандой четырех" (группа авторов Erich Gamma, Richard Helm, Ralph Johnson и John Vlissides. – Прим. пер.), содержит описание 23 базовых конструктивных шаблонов, включая Proxy, Visitor и Singleton.

• Analysis Patterns. Сокровищница высококлассных архитектурных шаблонов, выбранных из множества реальных проектов и переработанных в виде книги. Относительно быстрый способ перенимания опыта моделирования, полученного в течение многих лет [Fow96].

Команды и проекты

• The Mythical Man Month. Классическое произведение (не так давно переработанное) Фреда Брукса, о "подводных камнях", появляющихся в ходе организации команд разработчиков [Вго95].

• Dynamics of Software Development. Серия коротких очерков о разработке программного обеспечения в больших командах, сосредоточенных на динамике взаимодействия членов команды между собой, а также между самой командой и внешним миром [МсС95].

• Surviving Object-Oriented Projects: A Manager's Guide. "Вести с переднего края", сообщенные Алистером Кокбэрном, иллюстрируют многие опасности и ловушки, подстерегающие вас при управлении объектно-ориентированным проектом, особенно если это ваш первый проект. Г-н Кокбэрн дает подсказки и методики, позволяющие читателю решать наиболее общие проблемы [Сос97Ь].

Среды программирования

• Unix. У.Р. Стивенс написал несколько прекрасных книг, включая "Advanced Programming in the Unix Environment" и "Unix Network Programming" [Ste92, Ste98, Ste99].

• Windows. Книга Маршалла Брэйна "Win32 System Services" [Bra95] является кратким справочником по низкоуровневым интерфейсам прикладных программ. Труд Чарльза Петцольда "Programming Windows" [Pet98] стал своего рода Библией для разработчиков графических сред пользователя Windows.

• С++. Получив проект на языке С++, нужно бежать (а не идти) в книжный магазин и хватать книгу Скотта Мейера под названием "Effective С++" и к ней, возможно, книгу "More Effective С++" [Меу97а, Меу96]. При построении систем существенных размеров может понадобиться книга Джона Лакоса "Large-Scale С++ Software Design" [Lak96]. В поисках более сложных методик стоит обратиться к труду Джима Коплина под названием "Advanced С++ Programming Styles and Idioms" [Сор92].

Кроме того, книги из серии Nutshell издательства O'Reilly (www.ora.com) дают оперативное и всестороннее освещение разнообразных тем и языков, таких как perl, уасс, sendmail, внутренней организации Windows и регулярных выражений.

Интернет

Найти в Интернете нужную информацию трудно. Вот несколько ссылок, которые проверяются авторами как минимум раз в неделю.

• Slashdot. Под заголовком "News for nerds. Stuff that matters" (Новости для дебилов. Материал со значением) скрывается один из крупнейших сайтов сообщества Linux. Помимо регулярно обновляемых новостей из мира Linux сайт предлагает информацию по модным технологиям и проблемам, которые волнуют разработчиков.

www.slashdot.org

• Cetus Links. Тысячи ссылок на тему объектно-ориентированного программирования.

www.cetus-links.org

• WikiWikiWeb. Центральная база данных шаблонов и обсуждение шаблонов (в Портленде, США). Не являясь особо выдающимся ресурсом, данный сайт представляет собой интересный эксперимент по коллективному редактированию идей.

www.c2.com

Интернет-ресурсы

Приведенные ниже ссылки на ресурсы, доступные в Интернете, были действительны во время работы над книгой, но (Сеть есть Сеть!) к моменту выхода ее в свет могут сильно устареть. В этом случае можно попробовать общий поиск по именам файлов или же зайти на сайт Pragmatic Programmer (www.pragmaticprogrammer.com) и проверить имеющиеся на нем ссылки.

Текстовые редокторы

Emacs и vi – не единственные межплатформенные редакторы, но они распространяются бесплатно и находят широкое применение. Пролистав любой специализированный журнал (например Dr. Dobbs), можно найти ряд коммерческих альтернатив вышеуказанным редакторам.

Редактор Emacs

Редакторы Emacs и XEmacs имеют версии как для платформы Unix, так и для Windows.

[URL 1] Редактор Emacs

www.gnu.org

Новейший «крупнокалиберный» редактор, обладающий всеми возможностями своих предшественников. Кривая обучения Emacs почти вертикальна, но вас ждет щедрое вознаграждение по мере овладения тонкостями работы. Редактор также содержит отличную программу чтения почты и новостей, адресную книгу, календарь и дневник, приключенческую игру…

[URL 2] Редактор XEmacs

www.xemacs.org

Отпочковавшись от классического редактора Emacs несколько лет назад, XEmacs отличается более корректными внутренними командами и более изящным интерфейсом.

Редактор vi

Существует как минимум 15 различных клонов редактора vi. Редактор vim переносится на большинство платформ и является хорошим выбором при работе в различных программных средах.

[URL 3]The Vim Editor

ftp://ftp.fu-berlin.de/misc/editors/vim

Цитата из документации: "Редактор vi содержит большое количество усовершенствований: многоуровневая отмена команд, многооконный интерфейс с буферами, выделение синтаксиса, редактирование в командной строке, дополнение имен файлов, экранная справка, визуальный выбор объектов, и т. д."

[URL 4] Редактор elvis

www.fh-wedel.de/elvis

Усовершенствованный клон редактора vi с поддержкой X.

[URL 5] Emacs Viper Mode

http://www.cs.sunysb.edu./"kifer/emacs.html

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