Оформление и документирование программного кода |
72 |
Оформление и документирование программного кода
Данный раздел больше относится к курсовому проектированию, т.к. как именно на этом этапе Вам придется создавать свой программный код, но к этому этапу нужно быть готовым! Его нужно было бы начать с такого базового понятия как Паради́гма программи́рования (ПП), т.к. оформление и документирование кода это не самые первые этапы в жизненном цикле программы. ПП — это система идей и понятий, определяющих стиль написания компьютерных программ. Это способ концептуализации, определяющий организацию вычислений и структурирование работы, выполняемой компьютером [Википедия]. Для лучшего понимания этого важного вопроса отсылаю Вас к «библии программиста» [1].
1Стиль кодирования
Стиль кодирования (оформление исходного кода) или станда́рт оформле́ния ко́да (станда́рт коди́рования)англ( . coding standards, coding convention или programming style) — набор правил и соглашений, используемых при написании исходного кода на некотором языке программирования. Наличие общего стиля кодирования облегчает понимание и поддержание исходного кода, написанного более чем одним программистом, а также упрощает взаимодействие нескольких человек при разработке программного обеспечения. [Вики].
Стиль кодирования обуславливается парадигмой программирования (или стилем программирования ??). Для программирования МК, мы Вам рекомендуем освоить парадигму «автоматного программирования» [10]. Он очень эффективен для создания программ встраиваемой вычислительной техники, где, как правило, алгоритм работы устройства
достаточно хорошо представляется конечным автоматом.
Для освоения приемлемого для настоящей работы стиля кодирования, и получения желаемой оценки, Вам нужно использовать следующие источники [3,4,5].
Господа студенты, нам с вами для лучшего взаимопонимания придется пользоваться один стилем!
2Документирование ПО. Doxygen.
Средства документирования программного обеспечения. В курсе МПССАУ используется широко распространенное ПО Doxygen, обеспечивающие автоматизированное создание документации из исходного кода, предварительно написанного по специальным правилам. Программное обеспечение свободное, доступно в Интернете и на сервере кафедры ftp://192.168.77.178/_For_Students/MPSSAU/!KP/Doxygen.
ТУСУР, Миландр |
Каф. ЭСАУ |
Недяк С.П., Шаропин Ю.Б |
Весна 2013 г. |
Оформление и документирование программного кода |
73 |
2.1Doxygen глазами «старого программиста» ;-)7
Как в любом рабочем коллективе случаются лёгкие трения. Примерно год безуспешно проводилась агитация за использование doxygen. Никаких реальных преимуществ, кроме дополнительного мусора в исходных кодах, я как-то не замечал. Судите сами8.
Рисунок 1
7 Долго сопротивлявшегося узнать что-же это все таки такое...Doxygen.
8 На рисунке показан не заполненный шаблон будущего программно модуля взятый по рекомендации из [4].
ТУСУР, Миландр |
Каф. ЭСАУ |
Недяк С.П., Шаропин Ю.Б |
Весна 2013 г. |
Оформление и документирование программного кода |
74 |
|
Смысловую нагрузку несёт только шапка модуля. Всё остальное, за исключением |
||
строки |
#include “include.h” // , не несёт никакой смысловой информации. |
|
Мнение изменилось после более близкого знакомства с doxygen-ом. Оказывается, очень удобная вещь. Изучение производилось Ева-методом. Этот любопытно-игровой метод широко используется среди детей младшего школьного возраста. Если ребёнку сказать, что туда-то и туда-то залазить нельзя, то в отсутствии взрослых, он обязательно исследует, а что там, в запретном месте, есть интересненького. Заметим, что нет никаких принципиальных препятствий, чтобы реализовать этот режим автозагрузки, например, у роботов, у компьютеров вообще.
«Мой проект в качестве примера ты не бери, возьми лучше проект Фитона», - это рекомендация моего шефа. «Ща…, так я и послушал! Именно этот проект мы и возьмём в качестве примера». После запуска doxygen-а моё мнение насчёт полезности этого продукта резко изменилось в лучшую сторону. Теперь очень сожалею, что не использовал его раньше. Господа студенты, рекомендую для широкого использования, очень помогает в работе. Функционирует эта штука следующим образом.
Допустим, стоит перед вами задача быстро познакомиться с чужим исходным кодом и понять, как эта чужая программа работает. Кто сталкивался с подобной задачей, знают, что это далеко не просто, особенно, если программа большая. Запускаем doxygen и говорим ему: «Фас!», «Взять!». Несколько секунд работы и… вот она, голубушка, вся как на ладони. Вот что выдал мне doxygen после пробного (kickstart-ерного) запуска.
Рисунок 2
Один щелчок мышью и вся интересующая информация вам немедленно предоставляется.
Предоставляется, но, к сожалению, на английском языке. Попытка переключить на русский закончилась пока неудачно. По поводу выбора языка для комментариев есть очень
поучительная фраза в учебном пособии Е.О.Степанова и С.В.Чирикова [4] на стр.23. |
|
||||
«Все |
комментарии |
рекомендуется писать на английском языке. Программистов, не |
|||
владеющих |
английским, |
в природе не существует, а вот |
компиляторы, |
не |
|
поддерживающие кириллицу, к сожалению, встречаются часто.» |
|
|
|||
|
|
|
|
||
|
|
|
|
||
ТУСУР, Миландр |
Каф. ЭСАУ |
Недяк С.П., Шаропин Ю.Б |
Весна 2013 г. |
||