Главная страница Visual 2000 · Общий список статей

Oткрытая проектная документация? А может быть, лучше качественная!

Андрей Колесов

© Андрей Колесов, 2003
Авторский вариант. Статья была опубликована c незначительной литературной правкой в еженедельнике PC Week/RE (N 44/2004, с.56)


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

Обсуждение методологии создания качественных программ, безусловно, относится к категории вечных тем. Но если внимательно посмотреть на ход обсуждений за последние тридцать лет, то легко увидеть, что горячие дискуссии ведутся, в общем-то, по одним и тем же вопросам, новых идей выдвигается не так уже много. Однако, признаюсь, про "открытую проектную документацию" (Foundation of Open Project Documentation, FOPD) мне приходится слышать впервые (см. Шалыто А. Новая инициатива в программировании//PC Week/RE, ь 40/2003, с. 38). Вполне естественно, что любая новая идея требует критического осмысления...

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

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

Автор рассматривает идею FOPD как некоторое развитие движения Open Source Software, но при этом упускает из вида одно важное различие между исходным кодом и документацией. Исходный код программ — это совершенно объективная категория, она существует вне зависимости от желания разработчика. Если есть программа, то у нее не может не быть исходника. И вопрос заключается только в том, открывает ли программист этот код для посторонних, на каких условиях и т. д. А документацию нужно создавать отдельно, и, вообще говоря, не факт, что она будет адекватно описывать программу.

Кстати, и понятие "проектная документация" требует уточнения. Ведь по ходу статьи А. Шалыто говорится то о предпроектной документации, то об описании конечного продукта. Наверное, все же лучше обсуждать второй вариант, так как разработка ПО без полного описания реализуемого проекта представляется порой вполне обоснованным решением. Ведь все схемы экстремального программирования строятся на основе параллельного выполнения проектирования, кодирования и отладки. В каких случаях подобные подходы приемлемы — это уже другой вопрос, но то, что такая методика является работоспособной, в целом несомненно.

Здесь хотелось бы сделать небольшой комментарий по поводу определения "открытый". Сейчас не стоит обсуждать достоинства и недостатки подходов Open и non-Open с точки зрения создания качественного ПО. Обсудим только вопрос бизнес-рисков и гарантий разработчиков. В последнее время мы видим увеличение числа делового софта, распространяемого с исходным кодом. Но за словами поставщиков о желании предоставить максимальную гибкость пользователям подчас скрывается желание переложить с себя на тех же заказчиков полную ответственность за работоспособность и будущую модернизацию продукта.

Например, прошедшим летом я побывал на презентации новой системы документооборота для малых предприятий, распространяемую по принципу Open Source. Но любопытно: какая малая организация может себе позволить изучить 900 тыс. строк исходного кода на C++, чтобы внести нужное исправление? Не говоря уж о том, что предоставление исходного кода как бы делает ненужной передачу дополнительной документации. И здесь я полностью согласен с г-ном Шалыто: открытие исходных кодов не только не обеспечивает решение проблемы понимания программы, но порой даже усложняет ее.

В начало статьи

За качественную документацию!

Итак, в необходимости документации никто не сомневается. Однако чтобы инициатива, предложенная профессорами из Санкт-Петербурга, была более плодотворной, по-моему, надо заменить в ее названии слово "открытая" на "качественная". Ведь вопросы открытия связаны в основном с охраной авторских прав. Да и какой толк от открытой, но плохой (или просто неверной) документации?!

Правда, сказав "качественная", мы опять запутали вопрос, так как четко определить, что такое хорошо и что такое плохо — очень сложно. Но обсуждать требования к "качественной" документации и методы ее создания — можно и нужно, хотя бы для того, что научить этому молодых специалистов! Более того, можно не сомневаться, что компании-разработчики в целом успешно решают эти вопросы на внутреннем уровне. Другое дело, что они совсем не горят желанием размещать свои материалы в Интернете. А то, что "открытые" проекты не имеют надлежащей документации, к сожалению, отражает общее качество их реализации.

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

К сожалению, приведенный в статье А. Шалыто пример, когда "выдающийся программист не смог понять программу из шести строк на Си", говорит только о том, что это была очень плохая программа. Да, возможно, она использовала какие-то хитроумные конструкции для суперэффектного решения задачи. Но в этом случае автор исходного кода должен был написать пару строк комментариев...

Так что к перечню причин, почему компании не публикуют исходный код, мне хотелось бы добавить еще одну — далеко не все осмелятся выставить на всеобщее обозрение свои "произведения". Два года назад мне пришлось столкнуться с исходным кодом приложения, который одна солидная российская фирма по неосторожности опубликовала в Интернете: боюсь, что такая демонстрация отразилась отрицательно на ее технологической репутации (см. PC Week/RE, ь 9/2002, c.37).

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

Проблема заключается в том, что за эти годы существенно повысился уровень разделения труда в разработке ПО. Раньше весь цикл создания программ (проектирование, кодирование, тестирование, документирование) выполнялся одними и теми же людьми. Сегодня — не просто разными, но и различной квалификации. Соответственно при старой схеме разработчик сам мог управлять распределением своих усилий, отлично понимая, что его огрехи в проектировании или кодировании выйдут ему же боком при отладке или подготовке документации. А сейчас программист объективно заинтересован в минимизации собственных затрат, не очень заботясь о чужих проблемах. (Кстати, именно в решении задачи согласования работ на разных этапах проекта заключается одна из главных обязанностей руководителя проектов и современных средств поддержки жизненного цикла приложений.)

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

Итак, подведем итог: от открытой документации — к качественной, от написания хорошей документации — к созданию хороших программ! С некоторыми дополнительными соображениями автора на этот счет можно познакомиться на сайте "Размышления бывшего программиста" (www.visual.2000.ru/develop/talks/index.htm).

В начало статьи