Ведение - 2 |
16 |
2.2Оформление и документирование программного кода
Данный раздел больше относится к проектированию ПО, т.к. как именно на этом этапе Вам придется создавать свой программный код, но к этому этапу нужно быть готовым! Его нужно было бы начать с такого базового понятия, как Парадиигма программиирования (ПП), т.к. оформление и документирование кода это не самые первые этапы в жизненном цикле программы. ПП — это система идей и понятий, определяющих стиль написания компьютерных программ. Это способ концептуализации, определяющий организацию вычислений и структурирование работы, выполняемой компьютером2. Для лучшего понимания этого важного вопроса отсылаю вас к «библии программиста» [1].
2.2.1Стиль кодирования
Стиль кодирования (оформление исходного кода) или стандаарт оформлеания коада (стандаарт кодиарования) (англ. coding standards, coding convention или programming style) — набор правил и соглашений, используемых при написании исходного кода на некотором языке программирования. Наличие общего стиля кодирования облегчает понимание и поддержание исходного кода, написанного более чем одним программистом, а также упрощает взаимодействие нескольких человек при разработке программного обеспечения3.
Стиль кодирования обуславливается парадигмой программирования (или стилем программирования МК, мы Вам рекомендуем освоить парадигму «автоматного программирования» [10]. Он очень эффективен для создания программ встраиваемой вычислительной техники, где, как правило, алгоритм работы устройства достаточно хорошо
представляется конечным автоматом.
Для освоения приемлемого для настоящей работы стиля кодирования, и получения желаемой оценки, вам нужно использовать источники [3,4,5].
Господа студенты, нам с вами для лучшего взаимопонимания придется пользоваться один стилем!
2.2.2Документирование ПО - Doxygen
Doxygen — это кроссплатформенная система документирования исходных текстов, которая поддерживает C++, Си, Objective-C, Python, Java, IDL, PHP, C#, Фортран, VHDL и, частично, D.
Doxygen генерирует документацию на основе набора исходных текстов и также может быть настроен для извлечения структуры программы из недокументированных исходных кодов. Возможно составление графов зависимостей программных объектов, диаграмм классов и исходных кодов с гиперссылками.
Doxygen имеет встроенную поддержку генерации документации в формате HTML, LATEX, man, RTF и XML. Также вывод может быть легко сконвертирован в CHM, PostScript, PDF4.
С целью сокращения объёма данного методического пособия исходные тексты здесь приведены без надлежащего оформления. Все исходные тексты программ в лабораторных работах, предъявляемых на сдачу, должны соответствовать требованиям к оформлению программной документации. Лучше если вы сразу привыкните пользоваться Doxygen-ом.
Doxygen уже широко используемый продукт. Оформление кода по правилам этой программы создает особый стиль оформления, который использован и в библиотеки CMSIS и в библиотеки стандартных периферийных устройств. На рис.1 показан хелп-файл
2 https://ru.wikipedia.org/wiki/Парадигма программирования
3 https://ru.wikipedia.org/wiki/Стиль кодирования
4 https://ru.wikipedia.org/wiki/Doxygen
ТУСУР, "Миландр" |
Каф. ЭСАУ |
Недяк С.П., Шаропин Ю.Б |
Февраль 2017 г. |
Ведение - 2 |
17 |
MDR32F9Qx_Standard_Peripherals_Library.chm, созданный Doxygen-ом по исходным текстам CMSIS и библиотеки стандартных периферийных модулей версии 1.3.0. ф. "Миландр".
Рисунок 1 Хелп-файл к библиотеке стандартных периферийных модулей
В нашем курсе МПСАУ освоение Doxygen, и использование информационных ресурсов (SVN, Redmine), являются обязательными элементами дисциплины, и прописаны в рабочей программе.
По сгенерированному Doxygen-ом файлу легко ознакомиться с чужим исходным кодом и понять, как эта чужая программа устроена. Кто сталкивался с подобной задачей, тот знает, что это далеко не просто, особенно, если программа большая.
Заметьте, что все комментарии в описанных библиотечных модулях на английском языке. И это неспроста: по поводу выбора языка для комментариев есть очень поучительная фраза в учебном пособии Е.О.Степанова и С.В.Чирикова [4.] на стр.23: «Все комментарии рекомендуется писать на английском языке. Программистов, не владеющих английским, в природе не существует, а вот компиляторы, не поддерживающие кириллицу, к сожалению, встречаются часто.»
Ну не так уж и часто, поэтому до недавнего времени эта фраза как-то не воспринималась всерьёз. Пока однажды не встала задача адаптировать Си-код в среду MatLAB. В этой среде есть встроенный Си-компилятор, так вот он не совсем адекватно реагировал на кириллицу в комментариях. Чтобы это, в конце концов, понять было затрачено много рабочего времени.
Авторы упомянутого учебного пособия работают в том же учебном заведении, что и известный автор учебников по языку Си/Си++ Павловская Татьяна Александровна. В учебном пособии много толковых советов по выбору стиля программирования. Мы в своей работе стремимся их придерживаться. Следовательно, для наших студентов оно обязательно для ознакомления и использования.
Санкт-Петербургский государственный институт точной механики и оптики (бывший
ТУСУР, "Миландр" |
Каф. ЭСАУ |
Недяк С.П., Шаропин Ю.Б |
Февраль 2017 г. |