8.2.Оформление исходного текста программы

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

Понять смысл плохо оформленного исходного текста немногим легче чем объектный или исполняемый код. Образцы плохо оформленных ассемблерных текстов можно получить из исполняемого кода при помощи специальных программ, называемых дизассемблерами. Для того, чтобы понять назначение и принцип работы таких программ, приходится проделывать очень большую работу над этими текстами. И здесь дело не только в различии образа мышления автора программы и того, кто старается разобраться в ней. Любому профессиональному программисту знакомо состояние трудности восприятия, когда через некоторое время бывает необходимо доработать какую-нибудь программу. Говоря словами великого пролетарского поэта, поначалу он даже на свою (родную!) программу "глядит, как в афишу коза". Так что хорошее оформление нужно не только для других, но и для себя. Точнее, писать программу нужно так, чтобы с этим исходным текстом было удобно работать не только другим, но и самому себе.

Основным требованием к стилю программирования является простота и ясность изложения. Весьма желательно строить программу таким образом, чтобы она занимала меньше места в памяти, расходовала меньше ячеек ОЗУ и выполнялась быстрее. Этому способствует хороший стиль программирования, хотя оптимизация требует усилий и времени. Коротко и ясно написанный исходный текст облегчает отладку и сопровождение программы. Как наставляли нас школьные учителя русского языка и литературы по поводу сочинений, при их написании нужно следовать знаменитому афоризму "чтобы словам было тесно, а мыслям — просторно". Эту заповедь с учетом специфики программирования можно распространить и на оформление исходного текста.

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

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

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

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

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