Данные правила относятся не только к программированию на языке ассемблера, но и к программированию на других языках. Может быть, их трудно понять, не имея навыка в программировании, но «незнание основ не освобождает от ответственности».
Начните с написания инструкции для пользователя — для чего создается и каковы возможности вашей программы. А теперь немного усложните вашу инструкцию по применению вашей программы, подразумевая под «пользователем» программиста, использующего написанный вами код — зачастую этим программистом-исследователем будете вы сами.
Акт записи на обычном языке описания того, что делает программа и что делает каждая функция в программе, является критическим шагом в мыслительном процессе. Хорошо построенное, грамматически правильное предложение — признак ясного мышления. Если вы не можете это записать, то велика вероятность того, что вы не полностью продумали задачу или метод ее решения. Плохая грамматика и построение предложения являются также показателем поверхностного мышления. Поэтому первый шаг в написании любой программы — записать, что именно и как делает программа.
Итак, комментарии для вашей программы уже готовы. Теперь возьмите ваше описание по использованию и добавьте вслед за каждым абзацем блоки кода, реализующие функции, описанные в этом абзаце. Оправдание: «У меня не было времени, чтобы добавить комментарии» на самом деле означает — «Я писал этот код без проекта системы и у меня нет времени воспроизвести его». Если создатель программы не может воспроизвести идеи, воплощенные в программный проект, то кто же тогда сможет?
Работа программиста состоит из двух частей: разработать приложение для пользователя и сделать возможным дальнейшее сопровождение программы. Единственный способ решить вторую часть задачи — комментировать код. Причем комментарии должны описывать не только, что делает код, но и предположения, принятый подход и причины, по которым вы выбрали именно его. Кроме того, необходимо, чтобы комментарии также соответствовали коду. Пишите код так, словно тот, кто будет заниматься его поддержкой, — опасный психопат, знающий где вы живете. Хотя вы можете считать, что ваш код полностью очевиден и может служить примером ясности, без правильных комментариев понять его постороннему достаточно трудно. Парадокс заключается в том, что спустя неделю вы сами можете оказаться в роли этого постороннего.
Старайтесь использовать следующий подход при написании комментариев:

• перед каждой функцией или методом размещается одно или два предложения со следующей информацией:
  • что делает программа;
  • возникающие при этом предположения о программе;
  • что должно содержаться во входных параметрах;
  • что должно содержаться во выходном параметре в случае успешного или неудачного завершения;
  • все возможные выходные значения;
• перед каждой не совсем очевидной частью функции следует поместить одно или два предложения, объясняющие выполняемые действия;
• любой интересный алгоритм заслуживает подробного описания;
• любая нетривиальная ошибка, устраненная в коде, должна комментироваться, при этом нужно привести номер ошибки и описать сделанное исправление;
• правильно размещенные операторы диагностики, проверки условий, а также соглашения об именах переменных могут также служить хорошими комментариями и передавать содержание кода;
• писать комментарии так, будто сами собираетесь заниматься его поддержкой через пять лет;
• если возникла мысль «это хитро сделано» или «это ловкий трюк» — лучше переписать данную функцию, а не комментировать ее.

Если вы будете правильно писать комментарии — вы в безопасности, даже если программист из службы поддержки окажется психопатом.
Все писатели — это читатели. Вы учитесь, когда смотрите, что делают другие писатели. Я настоятельно рекомендую, чтобы, как минимум, члены группы программирования читали код друг у друга. Читатель может найти ошибки, которые вы не увидели, и подать мысль, как улучшить код. Для вас лучше присесть с коллегой и просто разобрать код строка за строкой, объясняя, что и как делается, получить какую-то обратную связь и совет. Для того чтобы подобное упражнение принесло пользу, автор кода не должен делать никаких предварительных пояснений. Читатель должен быть способен понимать код в процессе чтения. Если вам пришлось объяснять что-то вашему читателю, то это значит, что ваше объяснение должно быть в коде в качестве комментария. Добавьте этот комментарий, как только Вы его произнесли; не откладывайте этого до окончания просмотра.
На самом деле это также и правило литературного стиля. Если очень трудно объяснить точку зрения за один раз, то разбейте изложение на меньшие части и по очереди объясняйте каждую. То же самое назначение у глав в книге и параграфов в главе.
Некоторые программисты считают одним из недостатков языка ассемблера большее, по сравнению с языками высокого уровня, количество команд, но, по-моему, это одно из достоинств языка ассемблера.
Это относится не только к программированию на языке ассемблера.
Раньше, когда вы изучали в школе литературу, вам никогда не приходило в голову сдавать черновик письменного задания, если Вы, конечно, рассчитывали на оценку выше тройки. Тем не менее, многие компьютерные программы являются просто черновиками и содержат столько же ошибок, сколько и черновики ваших сочинений. Хороший код программы должен быть сначала написан, а затем отредактирован в целях улучшения (под «редактированием» имеется в виду «исправление»). Редактирование, как правило, приводит к сокращению кода, а небольшие программы выполняются быстрее.
Итак ваша программа заработала, а теперь постарайтесь переделать ее так, чтобы она стала максимально компактной и в тоже время максимально быстродействующей.
Такая оптимизация достигается в три этапа:

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

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

1. После каждой строки, где меняется значение регистра, указывать в комментарии, что в этом регистре
   

   Assembler

   1 2 3 4 5 6 7 8 9 10 11 12 13  proc CompareIcons ;,pIcon1,pIcon2 ;preventing stack frame creation mov ecx,[esp+4] ;ecx - pIcon1 mov edx,[esp+8] ;edx - pIcon2 mov eax,[ecx+LL_ICON.abscissa] ;eax - pIcon1->ordinate sub eax,[edx+LL_ICON.abscissa] ;eax - negative if pIcon1->ordinate < pIcon2->ordinate jnz .exit   mov eax,[ecx+LL_ICON.ordinate] sub eax,[edx+LL_ICON.ordinate] ;eax - negative if pIcon1->abscissa < pIcon2->abscissa   .exit: ret endp

2. Отступы делать не просто для циклов и ветвлений, но и для выделения любых ресурсов:

   Assembler

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 invoke OpenProcess,PROCESS_VM_READ or PROCESS_VM_WRITE or PROCESS_VM_OPERATION,\ FALSE,[pidListView] test eax,eax jz .exit xchg eax,ebx ;ebx - explorer.exe handle mov edx,[cbIconName] add edx,sizeof.LVITEM invoke VirtualAllocEx,ebx,NULL,edx,MEM_RESERVE or MEM_COMMIT,PAGE_READWRITE test eax,eax jz .allocationFailed xchg eax,esi ;esi - LVITEM address in explorer.exe   invoke SendMessage,[hListView],LVM_GETITEMPOSITION,[index],esi test eax,eax jz .msgFailed   ....................................   .msgFailed: invoke VirtualFreeEx,ebx,esi,0,MEM_RELEASE .allocationFailed: invoke CloseHandle,ebx .exit:

3. Подряд ищущих строк должно быть не более пяти-семи. Потом должен быть либо отступ (влево или вправо), либо визуальное отделение в виде одной-двух пропущенных строк. Для таких блоков часто можно сделать резюмирующий комментарий.
4. В отдельные функции выделять не только повторно используемые, но и логически связанные куски кода.
5. Давать осмысленные имена всему.
   • Никогда не использовать числовые константы. Если это смещение в структуре, то полностью описать структуру. Даже если это просто нуль, дать ему тоже имя. Например, CreateFile часто вызывается с нулём в третьем параметре. Мало того, даже MSDN в таблице с константами указывает там просто 0. Но потом при чтении трудно вспомнить, что же это за третий параметр, и даже имя NULL прочтение никак не упрощает. Вместо этого лучше определить константу вроде

     C
     1 FILE_SHARE_EXCLUSIVE = 0

   • Никогда не использовать безымянные метки.
   • Для больших проектов начинать имена функций с префиксов, определяющих к какой подсистеме или даже модулю относится функция. Например, если это модуль работы со связными списками, то функции вполне могут называться linked_list.create, linked_list.free, linked_list.push, linked_list.first и так далее. Это добавляет накладные на набор имён, но упрощает понимание любого кода, использующего модуль для работы со связными списками, и соответственно его последующую модификацию.
6. Структуризация проекта. Проект нужно делить на функции, модули (файлы), пакеты (папки) и подсистемы (опять папки). Хотя совсем маленьким проектикам до 5-10 тыс. строк вполне хватит только разделения на модули. В заголовочные inc-файлы нужно включать только определения, не генерирующие код. Функции должны находиться только в asm-файлах.
7. Инкапсуляция. Опять таки, если это модуль для работы со связными списками, то структуры, определяющие связный список и элемент связного списка, должны быть объявлены в этом модуле. Другим модулям знать, как работает связный список изнутри, не нужно.
8. Старайтесь не использовать прописные буквы с мнемониками инструкций и именами регистров

Книжка Code Complete Макконелла содержит ещё кучу советов, применимых ко многим языкам, включая ассемблер.

8