3Bit #01 03 января 2005

Программирование

Программинг - дизайн исходных кодов: основные требования к листинг программы, ориентированной на широкую публику.

(c) Dr.Lion/RSM
──────────────────────────────────────────
  Время от времени мне попадают в руки ис-
ходники других программистов спека. Основ-
ная  проблема состоит в том, что читабель-
ность и оформление этих исходников не под-
дается никакой критике. Да, при особом же-
лании  и  умной голове можно разобраться в
чужом труде или хотя бы найти интересующий
нас  участок  кода  и  вставить его в свое
творение без всякой оптимизации.
  Если  вы,  уважаемый  кодер, выставляете
исходные тексты своих программ на всеобщее
обозрение, то  не  забывайте, что их будут
читать  другие  люди,  которым,  зачастую,
трудно  понять, что творится в вашей гени-
альной голове. Оформляйте исходники в кра-
сивом, полном соответствующих комментариев
и  пояснений виде. Вот самые основные тре-
бования,  которым, на  мой  взгляд, должен
соответствовать  листинг программы, ориен-
тированной на широкую публику:

1.Функциональная  законченность кода. Если
  какой-то код выполняет строго определен-
  ную  масштабную  функцию  (функции), его
  лучше  выделить в отдельный подгружаемый
  исходник (прим. плеер AY музыки, програ-
  мма работы со стрелкой, блок арифметиче-
  ских функций и т.п.)

2.Весь текст исходника  должен быть оформ-
  лен в однотипном стиле, т.е. все воспри-
  нимается как единый текст.

3.Каждую функционально законченную подпро-
  грамму  нужно  назвать  именем,  которое
  максимально  отображает суть работы под-
  программы. Первой  строкой  подпрограммы
  должна быть строка-коментарий, отобража-
  ющая  полное название подпрограммы, либо
  описывающая   выполняемую  подпрограммой
  функцию. Имена меток внутри подпрограммы
  должны указывать на явную принадлежность
  к данной подпрограмме.

4.Каждый отрезок кода подпрограммы, испол-
  няющий свою особую подфункцию желательно
  снабжать  пояснительным комментарием. Но
  совсем не обязательно расписывать каждую
  комманду кода.

5.Любой ассемблер позволяет использовать в
  исходнике три типа комманд:
  а) полный набор транслируемых в код ком-
     манд Z80;
  б) общепринятые вспомагательные комманды
     (напр. ORG, DEFB, DEFW, DEFS, EQU);
  в) специфические   комманды   ассемблера
     (напр. для  ALASM комманды DISP, ENT,
     DUP, EDUP, MACRO и т.п.).
  Для того, что-бы исходник можно было ле-
  гко конвертировать в любой ассемблер, он
  должен  содержать минимальное количество
  комманд из группы в.

6.В начале текста желательно указывать ав-
  торство,  дату  последней  редакции, тип
  исходника  (независимый или зависимый от
  других  исходников), полный перечень ос-
  новных подпрограмм данного исходника.

7.Все метки желательно  писать с использо-
  ванием  строчных  букв попимо заглавных.
  Таким образом разнообразие меток и эсте-
  тический вид вам гарантирован.

8.Может еще что-то, уже и не вспомню.

  Примером по-человечески оформленного ис-
ходника может послужить любой мой исходник
из приложения журнала.
──────────────────────────────────────────