Книга: Программное обеспечение и его разработка

Документирование

Люди не очень-то любят составлять документацию на созданную ими продукцию. В то же время документация — это самое важное из того, что они должны сделать! Некий превосходный программист спроектировал и написал программу определения орбитальных характеристик спутника. Он первым закончил программирование, все работало правильно, память попусту не тратилась. Программа была написана на Фортране и занимала около 4 страниц плотного фортрановского текста. Он знал свою программу вдоль и поперек. Через 3 мес. его попросили добавить к своей программе несколько функций. Он достал документацию и принялся ее изучать. Три или четыре дня он пытался понять, что же происходит в его программе! А ведь он ее сам написал! Сколько бы сил он потратил, если бы это была чужая программа! А теперь представьте, что документации не было.

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

Наверное, наиболее распространенная в мире история о программировании — это рассказ о том, что программа работает, но ни один человек не знает, как это происходит, поскольку программист давно ушел, а документации нет. Эту историю часто рассказывают, потому что это весьма обычная ситуация.

Документация нам нужна для того, чтобы:

1) напомнить тем, кто создал эту программу, о том, как она устроена;

2) показать тем, кто придет после нас, как устроена программа, каков ее алгоритм.

Оглавление книги