2.5.2. Документирование программ

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

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

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

Самодокументирующий код означает, что имена переменных констант и функций выбираются такими, чтобы было интуитивно понятно ее назначение. Например, если функция называется «delay_3ms», то сразу понятно, что функция формирует задержку 3 мс.

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

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

2.5.3. Как язык Си соотносится со структурным проектированием

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

Метод проектирования сверху вниз может быть легко реализован на Си. Основная программа показывает общий ход реализации алгоритма управления. Чем дальше Вы погружаетесь в функции все более низкого уровня, тем более детально Вы знакомитесь с особенностями алгоритма управления.