[Eddy_Em 1]

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

[Obam 30]

2. Как выше в примере - число реальное, а единицы измерений неизвестно какие (мкс, мс, сек ??)

А через год нужно подкрутить код - и ищи концы по проекту. А так - комментарий присутствует :)

 

Дарю:

#define _RTTPrsclr_15ms (480u)

 

#define _RTT_30ms (2)// по _RTT_15ms_Tick

#define _RTT_250ms (17)// по _RTT_15ms_Tick

#define _RTT_300ms (20)// по _RTT_15ms_Tick

 

PAUSE (_RTT_1500ms);

 

Как показывает опыт, экономить на топтании клавы не стОит. (:

[juvf 10]

есть такое...... хороший код в коментариях не нуждается.

у Genadi Zawidowski скорее не комментарии, а референс мануал на его API.

 

У Velund пустые, не нужные комментарии.... типа таких

int a = 10; //создал переменную а, задал ей значение 10

 

2. Как выше в примере - число реальное, а единицы измерений неизвестно какие (мкс, мс, сек ??)

А через год нужно подкрутить код - и ищи концы по проекту. А так - комментарий присутствует :)

Для этого не нужны комментарии, нужны правильные имена.

t2 = _SET_TIMEOUT_MS(100);

GSMPower(0); - такой вызов без комментариев не очевиден

GSMPower(OFF), GsmModemPowerOff() или GsmModemOff() не нуждается в комментариях.

 

ps чужой код всегда плох. у каждого свой стиль, и только он true. Все остальное говнокод неправильное

[Alechek 0]

Комментариев мало не бывает ;)

И то правда.

Порой не хочется читать код, а просто прочитать по-русски, что же тут хотели сделать.

Бывает так, что комментарий верный, а вот в коде ошибка закралась....

 

Я, бывает, вначале комментариями пишу, что должно делаться, а потом уже эту последовательность последовательно превращааю в код.

Так как когда код уже написан, и в текущий момент времени понят тобой на 120%, то необходимость в комментариях (особенно развернутых) в этот момент вообще никак не очевидна.

 

GSMPower(0); - такой вызов без комментариев не очевиден

GSMPower(OFF), GsmModemPowerOff() или GsmModemOff() не нуждается в комментариях.

 

ИМХО, правильнее комментирование целого куска:

 

/* Выключаем модем правильно, см. ****pdf, 2.3.4 Power Down Cycle */

GSMPowerKey(1);

Delay(2000);

GSMPowerKey(1);

Delay(8000);

GSMPower(0);

 

 

[ViKo 1]

Моё.

/*!****************************************************************************
 @brief	Voltage Battery conversion & check
 @note		Однократное преобразование напряжения литиевой батареи
 @note		Temp.sensor, VRefint измеряются перед VBat/2 
 */
uint32_t Bat_check(void)
{
/*  Сначала запустить и дождаться преобразования инжектированных каналов
   2 * (480 + 12 cycles) : 32.8 us
   Заодно сработает прерывание от ADC3 - проверка уровня заряда аккумулятора
   Сбросить бит окончания преобразования инжектированных каналов  */
 ADC1->CR2 |= ADC_CR2_JSWSTART;
 ADC3->CR2 |= ADC_CR2_JSWSTART;

 while (!(ADC1->SR & ADC_SR_JEOC)) { }
 ADC1->SR &= ~ADC_SR_JEOC;

/*  Разрешить делитель напряжения батареи
   Задержка для включения не нужна  */
 ADC->CCR |= ADC_CCR_VBATE;

/*  Старт регулярного канала преобразования
   Ожидать окончание преобразования, 480 + 12 cycles : 16.4 us  */
 ADC1->CR2 |= ADC_CR2_SWSTART;
 while (!(ADC1->SR & ADC_SR_EOC)) { }

/*  Запретить делитель напряжения батареи  */
 ADC->CCR &= ~ADC_CCR_VBATE;

/*  Прочитать температурный датчик и опорное напряжение  */
 Sensors.Temp = ADC1->JDR1;
 Sensors.Ref = ADC1->JDR2;

/*  Прочитать напряжение батареи (умножить на 2) 
   При чтении DR автоматически сбрасывается бит окончания 
   преобразования регулярных каналов EOC
   Для перевода в мВ измеренное значение нужно преобразовать по формуле:
   mV = Data * 1210 / VRefData  */
 uint32_t Bat = (ADC1->DR << 1) * 1210 / Sensors.Ref;

/*  Округлить и уменьшить в 10 раз  */  
 if (Bat % 10 < 5)  Bat = Bat / 10;
 else Bat = Bat / 10 + 1;  
 //  NumStat1_print(Bat);

/*  Проверить, укладывается ли напряжение в допустимый диапазон  */
 return Bat;
}

[Obam 30]

"Я, бывает, вначале комментариями пишу, что должно делаться, а потом уже эту последовательность последовательно превращааю в код."

Присоединяюсь…

 

"Так как когда код уже написан, и в текущий момент времени понят тобой на 120%, то необходимость в комментариях (особенно развернутых) в этот момент вообще никак не очевидна."

ОтлОжите его (этот код) не менее чем на пол-годика, займётесь каким-нибудь перпендикулярным проектом и после, вернувшись, похвАлите себя за то, что не зажмотились в "…комментариях (особенно развернутых)…"

Я гарантирую это (;

[jcxz 184]

У Velund пустые, не нужные комментарии.... типа таких

int a = 10; //создал переменную а, задал ей значение 10

Согласен. Такие комментарии делают обратное - только ухудшают читаемость исходника, загромождая его.

 

Порой не хочется читать код, а просто прочитать по-русски, что же тут хотели сделать.

Бывает так, что комментарий верный, а вот в коде ошибка закралась....

А бывает и наоборот.

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

Поэтому я, например, при первоначальном написании, комменты почти не пишу. А пишу их только когда исходник более-менее устаканится и заработает как надо.

[Forger 17]

Поэтому я, например, при первоначальном написании, комменты почти не пишу. А пишу их только когда исходник более-менее устаканится и заработает как надо.

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

Например, много лет назад, пригодилась эта: "Веревка достаточной длины, чтобы выстрелить себе в ногу", ее легко найти в гугле.

Правда, помню, что с многими моментами я там был не очень согласен. Это мягко говоря )))

Но потом попалась в руки эта книжка: Мартин - "Чистый код".

К тому моменту она была мне очень кстати - вычитал ее запоем всю до дыр :)

 

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

Благодаря этой книжке мне удалось составить собственную "конвенцию именования", очень лаконичную и простую, но при этом предельно однозначную, что значительно улучшило читаемость кода:

 

ps, Картинка не ради разведения очередного холивара, а, просто - вдруг кому-то пригодится ))

[juvf 10]

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

не ради разведения очередного холивара, а, просто - вдруг кому-то пригодится ))

а мне помогла небольшая шпаргалка

________________________.pdf

[Forger 17]

а мне помогла небольшая шпаргалка

Прям с языка сняли!!! :)

 

Правда с некоторыми пунктами я не очень согласен, в частности с теми, которые имеют приписку "Это правило пришло из математики...".

Предпочитаю математику (да и не только математику, но и другие дисциплины) с ее короткими и малоинформативными именами и именами в коде не смешивать, не путать "мух с колетами" :)

Скажем "скорость" называть не 'v', а как положено - velocity, т. е. в данных случаях сокращения, пришедшие из фундаментальных вековых дисциплин, могут сильно усложнить чтение кода.

Дело в том, что в те далекие времена английский не был, можно сказать, "всемирным" языком, и потому чаще всего использовались лишь сокращения от латинских названий терминов,

К тому же практически все писалось от руки.

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

 

Например, вместо "i" использую переменную, носящую конкретный смысл для кода, где она используется: index, iterarator, value ..., составные: itemIndex, objectIterator и и т.п.

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

 

Для отладки полноценные имена (в том числи и счетчики циклов, итераторы и т. п.) тоже очень полезны - в окне watch переменные несут явный и однозначный смысл.

Разумеется, при условии, что переменные и объекты названы правильно :)

 

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

[Alechek 0]

Благодаря этой книжке мне удалось составить собственную "конвенцию именования", очень лаконичную и простую, но при этом предельно однозначную, что значительно улучшило читаемость кода:

Если уж пошла такая пьянка по поводу стилей, то при переходе на C++ я решил придерживаться

 

https://google.github.io/styleguide/cppguide.html

 

[Forger 17]

Если уж пошла такая пьянка по поводу стилей, то при переходе на C++ я решил придерживаться

А почему лишь C++?

Я вот использую единые принципы именования и структурирования не только в С/С++ коде, но и в других языках, средах, CAD-ах и т. п.

Например, очень удобно писать код для МК, если цепи на схеме (AD) названы таким образом, что позволяет в коде использовать точно такие же имена для пинов.

[zltigo 0]

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

Очень, очень массовое явление :(. Особенно убивает, когда комментарий провильный, а то, что в исходнике с ошибкой.

Поэтому я, например, при первоначальном написании, комменты почти не пишу. А пишу их только когда исходник более-менее устаканится и заработает как надо.

Именно так. Причем такое комментирование прекрасно совмещается с общей вычиткой и оптимизацией исходника.

 

[Aaron 1]

а мне помогла небольшая шпаргалка

 

Блин, товарищи, поздновато выложили :) Как раз сейчас разродился наконец оформить требования к стилю кодирования в своём отделе, уже написал почти :) Но всё равно подглядеть чужие готовые рекомендации незазорно, чтобы ничего не упустить!

[Forger 17]

Как раз сейчас разродился наконец оформить требования к стилю кодирования в своём отделе, уже написал почти

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

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

Проекты относительно небольшие, команда не требуется.

Поэтому каждый "ваяет" как пожелает.

Главное - положительный результат на выходе )))