CC BY
42
АКТУАЛЬНЫЕ ПРОБЛЕМЫ ДОКУМЕНТИРОВАНИЯ ИСХОДНЫХ КОДОВ РАЗРАБАТЫВАЕМОГО ИТ-ПРОДУКТА И ПУТИ ИХ РЕШЕНИЯ
А.С. Михалев, старший преподаватель Я.С. Иванова, студент А.Н. Конюхова, студент Сибирский федеральный университет (Россия, г. Красноярск)
Аннотация. Данная статья посвящена вопросам документирования исходных кодов. В тексте представлены две точки зрения относительно использования процедуры документирования в процессе разработки it-продукта. С одной стороны, авторами приводятся аргументы в пользу необходимости применения процедуры документирования, даётся обоснование преимущества её использования. С другой стороны, рассматриваются проблемы, встречающиеся на пути у разработчика. Для выявленных проблем в статье делается попытка предложить пути по их устранению.
Ключевые слова: ИТ-продукт, исходный код, процесс документирования.
Человек, связавший свою специальность так или иначе с программированием, должен понимать, что данная деятельность обязательно должна сопровождаться документированием исходных кодов. И тут перед будущим специалистом встает ряд следующих вопросов: «Что из себя представляет процесс документирования, и для чего он нужен? Какие проблемы встречаются на стадии документирования исходных кодов разрабатываемого ИТ-продукта? Какие существуют методы решения данных проблем?»
В среде разработчиков программного обеспечивания под термином «документирование» подразумевается добавление комментариев в исходный код [1]. С помощью данных комментариев логика кода делается более понятной, а также улучшается и сама архитектура программного продукта. Отсутствие же документации кода приводит к плохой его читаемости и к сложному техническому обслуживанию для других членов ИТ-команды, работающих над продуктом.
Существует ряд причин в пользу применения технологии документирования исходных кодов, которые отвечают на вопрос, зачем же всё-таки необходим указанный процесс [2]. Первой причиной можно обозначить тот факт, что документирование позволяет грамотно организовать работу команды разработчиков ИТ-продукта. Данная деятельность предоставляет четкое разграничение зон ответствен-
ности между участниками проекта. Второй причиной является отсутствие недопониманий среди разработчиков. Команде предоставляется возможность «говорить на одном языке». Экономия временных ресурсов является третьей причиной, ведь происходит сокращение сроков восстановления работоспособности всех сервисов и систем в случае каких-либо сбоев или же разрушения проекта [3, 4]. Помимо этого, в пользу документирования выступает удобство сопровождения ИТ-продукта. Трудоёмкой будет не только передача недокументированного кода, но и может возникнуть сложность при самостоятельном сопровождении.
И даже с учетом всех вышеперечисленных преимуществ, документирование является кропотливым процессом. Многие программисты не любят это дело и стараются всячески избежать этой работы различными способами. Этот факт и является основной проблемой, встречающейся при документировании исходных кодов разрабатываемого ИТ-продукта. Данная работа является затратной и требует усидчивости. В то же время, не каждый разработчик умеет писать комментарии на высоком уровне, что так же является проблемой. Тому, кто будет работать с данным исходным кодом, будет довольно сложно разобраться в написанных комментариях, либо вообще он не сможет этого сделать. Для ведения документации необходимо будет привлечение отдельных специалистов, или
13S
же придётся заставлять программистов делать то, что они не любят или не умеют. Даже если будут приглашены специалисты, то нельзя с высокой точностью утверждать, что им удастся разобраться в написанном коде, чтобы в дальнейшем написать хорошие комментарии к нему [5-7]. А также, проблемой при документировании будут инструменты для генерации документации из исходного кода. В данной среде существует многообразие различных программ для документирования. Именно поэтому для разработчика, столкнувшегося впервые с этим процессом, будет весьма сложно правильно сориентироваться и выполнить документацию, удовлетворяющую всем стандартам. Следует отметить следующий момент, который может привести в затруднительное положение: если комментарии "не встраиваются в исходный код", а представляют собой отдельную документацию, то стоит вопрос, где её хранить, чтобы разработчики имели к ней доступ. На ряду с вышеперечисленными проблемами не стоит забывать, что с каждым годом идет процесс усовершенствование кодов, появляются новые языки программирования. Так, происходит устаревание уже существующей документации. Код меняется - документация остается прежней. Комментарии необходимо держать в актуальном состоянии, что ведет к увеличению работы вдвое.
С решением данных проблем постараемся разобраться подробнее. Избежание документирования можно предотвратить, если внести данный аспект в обязательные требования при разработке ИТ-продукта. Таким образом, программистам уже никак не удастся избежать данной работы, ведь это будет входить в их обязательства. Введение данного процесса в систему разработки приведет к тому, что все специалисты уже не смогут представить свою деятельность без документирования.
Проблема отсутствия умения написания комментариев на высоком уровне у каждого разработчика решается следующим образом: еще на начальных этапах исследования программной работы, специалисты должны понимать всю важность документации и ответственно подходить к изучению данного процесса (стараться улуч-
шить и преумножить свои знания по данному вопросу). Стимуляцией может послужить тот факт, что квалифицированный специалист, который прекрасно разбирается не только с разработкой кода, но и с написанием к нему комментариев, пользуется высоким спросом на трудовом рынке.
Чтобы справиться с нелегким выбором кодировки, необходимо ознакомиться с некоторыми из них. Примером может послужить популярный инструмент для генерации документации из исходного кода Doxygen. Этот инструмент дает возможность документировать на языках C, C++, C#, Java, PHP, Python, VHDL, Fortran. Doxygen также полезен в создании онлайн HTML документации. Самое главное преимущество использования Doxygen это то, что вы сможете видеть последовательность всей документации исходного кода. Эта последовательность поможет вам создать структуру кода с применением недокументированных исходных файлов. Другим популярным инструментом для создания текстовых документов будет являться Sphinx. Он удобен при использовании систем управления версиями, которые предназначены для отслеживания изменений. Sphinx применим с такими языками программирования, как С, С++ и Python. Данный инструмент практикуется как для проектной документации, так и для документации кода. В свою очередь, еще одним востребованным пакетом выступает LaTex, который является де-факто стандартом при документировании научных проектов. Latex универсален, и поэтому он может использоваться для других типов проектов, в частности для кода и проОектной документации. Создавая свой документ, разработчик указывает логическую структуру текста, на основе которой LaTeX формирует результат [8].
Таким образом, мы тщательно ознакомились с таким понятием, как документирование исходных кодов, определили суть проблем документирования, обозначив актуальные пути их решения, базируясь на подходах обозначенных в работах [9-11]. Поэтому, каждому специалисту программной инженерии необходимо внимательно изучать данную тему и стараться совершенствоваться в данной области.
Библиографический список
1. Идеальная и реальная документация программных продуктов // http://smartsourcing.ru [Электронный ресурс]. Режим доступа: http://smartsourcing.ru/blogs/poleznye_tehnologii_i_produkty/961
2. Документирование в разработке ПО // https://habrahabr.ru [Электронный ресурс]. Режим доступа: https://habrahabr.ru/post/215837/
3. Евдокимов И.В. Методика исследования систем управления предприятий для целей информатизации // Труды Братского государственного университета. Серия: Экономика и управление. - 2007. - Т. 1. - С. 284-288.
4. Евдокимов И.В. Менеджмент качества и управление развитием системы обработки экспертной аналитики // Труды Братского государственного университета. Серия: Экономика и управление. - 2015. - Т. 1. - С. 212-219.
5. Евдокимов И.В. Проблема и показатели качества программного обеспечения // Труды Братского государственного университета. Серия: Экономика и управление. - 2009. - Т. 1. - С. 121-124.
6. Evdokimov I.V., Domantsevich V.S., Konyhov V.A. The use of online applications for project management for planning in IT-management // Современные информационные технологии. - 2017. - №25 (25). - С. 44-47.
7. ВахрушеваМ.Ю., Евдокимов И.В. Разработка программного обеспечения аналитических информационных систем // Труды Братского государственного университета. Серия: Экономика и управление. - 2014. - Т. 1. №1. - С. 196-199.
8. 10 инструментов для безупречного документирования кода // http://blog.liveedu.tv [Электронный ресурс]. Режим доступа: http://blog.liveedu.tv/10-best-code-documentation/
9. Евдокимов И.В. Аспекты внедрения информационных технологий на предприятиях г. Братска // Труды Братского государственного университета, Серия: Экономика и управление. - 2006. - Т. 1. - С. 144-148.
10. Евдокимов И.В. Кадровое обеспечение внедрения SCADA-систем на предприятиях // Труды Братского государственного университета. Серия: Экономика и управление. -2005. - Т. 1. - С. 116-119.
11. Евдокимов И.В. Адаптация стандартов программных средств к проектам в области информационных технологий // Труды Братского государственного университета. Серия: Экономика и управление. - 2010. - Т. 2. - С. 97-101.
ACTUAL PROBLEMS OF DOCUMENTATION OF SOURCE CODES DEVELOPED IT PRODUCT AND THE WAYS OF THEIR SOLUTIONS
A.S. Mikhalev, senior lecturer Ya.S. Ivanova, student A.N. Konyukhova, student Siberian federal university (Russia, Krasnoyarsk)
Abstract. This article is devoted to the issues of documenting source codes. The text presents two points of view regarding the use of the documentation procedure during the development of the IT-product. On the one hand, the authors give arguments in favor of the need to apply the documentation procedure, and justify the advantages of using it. On the other hand, problems encountered in the way of the developer are considered. For the identified problems, the article attempts to suggest ways to eliminate them.
Keywords: IT- product, source code, documentation process.
