Оформление кода

[gauss]

Доброго вечера всем!
Пишу код на ассемблере уже довольно давно. Проги все сложнее, все больше...
Естественно, пытаюсь оформлять, использую .def, .equ, различные макросы,
чтобы хоть как-то повысить уровень абстракции.
Мой вопрос, собственно говоря, именно по макросам:
Со временем они начинают накапливаться, их становится реально много. Но вот, например, выкладываю
куда-либо пример кода. И что, все макросы надо заменять на спрятанный внутрь код?

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

[pyzhman]

Стандарт один - завязка, кульминация и развязка. А пишут все по-разному. У Чехова один стиль, у Пушкина другой. Но все читаемы. Главное, чтобы буквы были знакомые.

[gauss]

pyzhman, под читаемостью я понимаю удобство восприятия.
Скажем, заглянете в код через несколько месяцев(а то и больше) - сможете разобраться в логике работы программы?

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

[YS]

Пишите обширные комментарии. Это очень помогает читателям кода. Причем желательно на английском - национальные кодировки везде разные, а латиница везде одна. Только ради бога, не транслитом - это выглядит... Нехорошо. Да и коллеги по всему миру на английском поймут.

Также рекомендуется давать переменным осмысленные имена.

Проги все сложнее, все больше...

Ну и да, в таком случае с некоторого момента проще перейти на Си. Правда, это не отменяет совета насчет написания комментариев.

[ARV]

проще перейти на Си. Правда, это не отменяет совета насчет написания комментариев

на счет комментариев я бы не стал так категорично утверждать...

[YS]

В любом случае, лучше когда они есть, чем когда их нет. Если читающему они покажутся мешающими, он может просто удалить их.

[ARV]

не хотелось бы повторяться... но лучше не в любом случае

Код: Выделить всё

a = a * 2; // удваиваем переменную

я бы убивал...

[YS]

Ну так и что? Да, такой комментарий абсолютно бесполезен, но и вреда от него ноль.

[ARV]

не можешь сделать добро - не делай ничего
бесполезный комментарий вреден как минимум тем, что отучает делать полезные комментарии.

[gauss]

Не надо комментировать каждую строку - код разделяется тем же энтером на отдельные блоки, отвечающие за
что-то одно, вот такой блок и комментируется

И комментятся не команды, а СУТЬ данного блока, может быть, какие-либо переменные, нюансы...

[ARV]

gauss, если вы хотите в порядке самообразования получить дополнительное удовольствие от макросов - осваивайте GNU AVR-AS вот там макросы - это МАКРОСЫ, а не жалкое убожество от Atmel...

что касается стиля оформления, то с ассемблером я просто не знаю, как сделать одновременно красиво, удобно, полезно, для всех и навсегда. наверное, это просто нереально...

P.S. написал и вдруг подумал: а с чего это я решил, что вы пишите на ассемблере под AVR?! так что если не в тему - извините...

[gauss]

ARV, наверное, это в силу особенностей языка

[pyzhman]

заглянете в код через несколько месяцев

Я забываю собственный код уже через пару дней, после выходных точно. Посему акромя каментов, в чем согласен с YS, имею нехилую стопку черновиков.

Код: Выделить всё

a = a * 2; // удваиваем переменную

Согласен. А за это:

Код: Выделить всё

a*= 2; // удваиваем переменную

орден давать.

[OKF]

А ещё случаются "обманывающие" комментарии, которые вводят в заблуждение, а также запутывающие, мешающие, дублирующие, тупые, идиотские и т.п.
А нет комментариев - нет и проблем.))
Только блоки. Только непонятные.
Внутри в крайнем случае. Только нюансы.

[ARV]

А за это:

Код: Выделить всё

a*= 2; // удваиваем переменную

орден давать.

если речь о комментарии - то только посмертно

[СКАЗОЧНИК]

Знаю, что правильно писать кроме кода и комментарии тоже надо учится...
Но и учиться надо с чего-то начинать. А когда уже самому глупые и ненужные комментарии мешать будут, то и писать их перестанешь...
А вот конструкции на Си, которые "упрощают" написание... Лучше да. Орден.

А я вот привык и мне нравится отделять блоки на ассемблере отступами. Ну, как в С. Тогда мне понятнее, что этот блок идет как вложенный для того, что сверху написано.

[dr.doc]

Мне очень помогает написанный словами (вложенная картинка в папку с проектом) краткий алгоритм работы всего прибора. Еще - очень хорошо, когда встречаемые по коду сложные участки также комментируются. Также стараюсь отлаженные блоки с комментариями закидывать в include файлы. Тогда новый проект делается намного проще и по отображаемому коду короче. Подключил блок математики - а там в заголовке написано, что на входе, а что на выходе...

[Siarzhuk]

Код: Выделить всё

a*= 2; // удваиваем переменную

орден давать.

ИМХО хватит и медали, а орден не менее чем за

Код: Выделить всё

a <<= 1; // удваиваем переменную

[gauss]

Также стараюсь отлаженные блоки с комментариями закидывать в include файлы.

dr.doc, тут один минус есть - если подключается слишком много и названия функций/блоков "плохие" -
придется слишком часто лезть в инклюдники.

Просто об оформлении задумался сравнительно недавно - после интенсивного курса С++.
Именно поэтому функции с большой буквы, переменные с маленькой и в CamelCase -нотации.
Внутри функций, между метками у кода отступ в 1таб, также на командах условного перехода и с разными sbrc/sbic.


Ну и препроцессор, конечно

[pyzhman]

посмертно

Зачем так сразу. Повторение - мать учения. Но улыбнуло.

Код: Выделить всё

a <<= 1; // удваиваем переменную

Пробел и два знака < требуют большего пальцедвижения нежели *. Засим был отсечён этот вариант.