Интернет, компьютеры, софт и прочий Hi-Tech

Подписаться через RSS2Email.ru

Исходный код — лучшая документация для программиста

Исходный код — лучшая документация для программиста

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

И вот программа готова и успешно внедрена. Фирма своевременно поставляет обновления, исправления, заплатки для дыр в безопасности, оказывает поддержку, консультирует и всячески обслуживает своё изделие, добавляя функциональность по просьбе клиента, что-то меняя, совершенствуя и так далее. Однако наступает очередной финансовый кризис — и всё, нету больше фирмы.

Но менеджмент компании в отчаяние не впадает. Берёт исходный код крайне важного приложения и обращается к другим программистам, которые продолжают поддержку софта.

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

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

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

Отдельно следует сказать о названиях функций и переменных. Они должны быть как можно более очевидным. Например, даже без сопровождающего комментария понятно, что sum — это сумма. Но если назвать sm или вовсе s, то не догадается даже телепат, доведётся постоянно смотреть расшифровку в документации. (Впрочем, о документации — далее).

Функции традиционно именуются составными словами, каждое из которых начинается с большой буквы, а первое — глагол, определяющий действие (функция ведь действительно что-то делает). К примеру, CountThisSum или SetNewDate. Другой способ: сount_this_sum, set_new_date, такое тоже можно читать без рези в глазах.

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

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

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

Комментарий, предназначенный в первую очередь для вышеуказанной генерации, называется документирующим. Обычно он подробный, многострочный (/* язык C ещё не забыт */) и располагается непосредственно перед описываемым элементом.

Может состоять из нескольких частей: краткого описания, развёрнутого пояснения и дескрипторов со значком @ в начале (@author, @version, @global, @name, @return etc.) Части разделяются пустыми строками; каждая строка начинается с дополнительной звёздочки *. Например:

/**
* Краткое описание объекта
*
* Подробное описание, для чего вообще этот элемент нужен
*
* @author Антуанетта Урюкина
* @version 1.0
* @package sample
*/

Список популярных программ для автоматического создания документации довольно обширен. Для обработки исходных кодов, написанных на C, C++, Java, PHP используется Doxygen. Отдельно для Java есть Javadoc. Для Delphi и Pascal — PasDoc. Даже JavaScript можно обработать в JSDoc.

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

Автор: vanilinkin, специально для xBB.uz, 31.08.2011


Предыдущие публикации:

Биржа долевых инвестиций SIMEX.

Последнее редактирование: 2011-08-31 11:24:27

Метки материала: программист, исходный код, документация для программиста, source, ит, по, программа, программы, it, софт, программы для компьютера, программирование, software, программное обеспечение, разработка по, информационные технологии, программное обеспечение по

Оставьте, пожалуйста, свой комментарий к публикации

Представиться как     Антибот:
   

Просьба не постить мусор. Если вы хотите потестить xBB, воспользуйтесь кнопкой предварительного просмотра на панели инструментов xBBEditor-а.


© 2007-2017, Дмитрий Скоробогатов.
Разрешается воспроизводить, распространять и/или изменять материалы сайта
в соответствии с условиями GNU Free Documentation License,
версии 1.2 или любой более поздней версии, опубликованной FSF,
если только иное не указано в самих материалах.