Как лучше комментировать код?

Здравствуйте. У меня есть вопросы по коментированию кода.
1. Какой язык лучше использовать для коментариев (русский или английский)?
2. Нужно ли коментировать действие каждой строки (вплоть до "I++ // увеличение значения i")?
3. Где лучше располагать коментарии: в коде или справа от кода?

0

Надеюсь что в некрофилии не обвинят что такую тему откопал...

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

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

Понятное дело что
писать не стоит, но
вполне.

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

Причем иногда комментарии очень нужны. Современное программирование во всю использует потоки, обратные вызовы и прочую магию, код становится не линейным и отследить его иногда сложно. Нужно добавлять комментарий что вот тут мы ждем другой поток, тут мы получим данные по прерываю, а тут мы вызываем функцию, а она нам ответит через колбек.
Или меняете вы запись в одной таблице, а записи в другой таблице меняются "сами" так как там foreign key. Вот как надо написать код что бы он это прокомментировал сам?

Ну и каждую функцию/метод тоже подробно описать желательно, особенно если это не checkCRC, а что то более сложное с учетом каких-нить нюансов.

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

ЗЫ главное не лениться и менять коментарии если меняется код

0

А что, не видно, что счётчик на единицу увеличивается. Об этом надо написать?

Правильные комментарии, на мой взгляд, бывают трёх видов:
1. Объяснение, почему выбрано такое решение (быстродействие, затраченная память, особенности железа, особенности пользователей, планирование дальнейшего развития кода). Эта инфа вообще никак не связана с кодом, в коде нет этих сведений.
2. Комментарии-заголовки. Они разбивают код на логические части. Отчасти связаны с кодом.
3. Некоторые сложные моменты, например, какие-то трудно воспринимаемые условия if.

0

Сообщение от Mikhaylo А что, не видно, что счётчик на единицу увеличивается. Об этом надо написать?

Я хотел сказать что комментарии должны описывать не то делает конкретный код, а какие задачи он решает в общей задаче программы.
Пример может немного не корректный, да, переменные надо называть так что было понятно, но иногда бывает что у нас принимаются данные, из которых мы "выдергиваем" только именно данные, без заголовков пакетов и контрольных сумм, а из этих данных выдергиваем нужные нам (например с устройcтва идет поток телеметрии, а нас интересует только данные по температуре) и получается у нас уже будут три счетчика принятых байт и будут называться они как то Received_bytes_packet, Received_bytes_data, Received_bytes_temperature и тут лучше прокомментировать кто из них кто...
Вообщем я считаю что чем больше комментариев тем лучше, даже если они очевидные, то хуже не будет.

0

По поводу использования русского языка. После введения многобайтной кодировки
такой кошмар стал твориться, что лучше его избегать.
Иначе рискуешь в любой момент увидеть кракозяблы вместо своего текста.
У меня был случай, что я так и не смог понять, что произошло, что это за
коды и откуда они взялись.

0

Как правило это выявляется сразу. То что все слетело, скорее всего надо было файл пересохранить в кодировке utf8, там вначале вроде два байта какие то добавляются, после этого все работает.
После введения многобайтной кодировки как раз все стало нормально, вот когда были 866, 1251 вот тогда проблемы иногда были

0

Сообщение от Alex1126 Вообщем я считаю что чем больше комментариев тем лучше, даже если они очевидные, то хуже не будет.

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

0

Сообщение от Alex1126 Отдельно добивают ораторы говорящие что если код не понятен то надо его переписать так что бы было понятно и не использовать комментарии. Причем последнее заявляется очень категорично.

Считайте меня одним из них Пройдет не так уж много времени, и, вероятно, Вы устанете писать примечания и придете к тем же выводам

И это пройдет..

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

0

Сообщение от Igor3D Считайте меня одним из них Пройдет не так уж много времени, и, вероятно, Вы устанете писать примечания и придете к тем же выводам

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

0

Сообщение от Alex1126 Что касается языка, то если вы не пишите код который вы будете распространять на весь мир,

Будете. (Здоровые) амбиции - неотъемлемая часть программиста, без этого он просто .. (не хочу быть грубым)

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

Только на английском. Некоторые реагируют неадекватно: "стесняешься родного языка?" и.т.п.

Я доволен что "международный язык" - не мой родной. Англичанина корежит от "color" (без "u"), но одернуть-то нельзя. Над своим языком я бы такого издевательства не вынес. И английский подходит гораздо лучше, особенно учитывая устоявшиеся термины. Все эти "иконки", "щелкнуть мышкой", "потокобезопасность" и.т.п. просто ужасны Технический английский дисциплинирует, учит писать кратко и емко

0

Дело в том, что комментарии пишутся не только для себя но и для других. У нас над одним проектом могут работать несколько разных разработчиков - один прошивку для плис делает, второй микроконтролер программирует, третий программу под винды пишет. И иногда есть необходимость "поделиться" кодом, чтобы человек который делает устройство "с той стороны" посмотрел что там не так, почему не работает и прочее. Да, можно описать протокол, описать все технические ньюансы, но в процессе разработки "концепция" может и измениться и проще дать ссылку на репозиторий. А тот кто, например, с плис работает, он в си может быть не бумбум, поэтому такие понятия как "код сам себя должен коментировать" тут вообще не в кассу. Там по смыслу конечно понятно что то, но когда есть комментарии то все становится понятно.
Ну и опять же многие IDE позволяют в хинтах давать описание функции и переменным, если к ним добавлены комментарии.
Ну и уровень английского у всех разный и что бы не вызывать путаницу всякими receive_byte и received_byte нам и мне проще на русском общаться

ЗЫ Ни к чему не призываю, написал что практикую сам, однако хочу заметить что излишне прокомментированный код поймут все, а тот который сам себя комментируют не только лишь все

0

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

0

Сообщение от Alex1126 Да, можно описать протокол, описать все технические ньюансы, но..

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

0

Сообщение от Igor3D Так вот где собака порылась! Оказывается, обильные примечания - это вместо документации, которую (как всегда) писать никому неохота Ну вообще-то ф-ционал примечаний и доки разный, но если в Вашем проекте это устраивает - на здоровье. А может и кого-то еще устроит - но далеко не всех

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

0

Аналитики пишут user story перед началом разработки, техписы - раздел "Порядок действий" в РЭ - после разработки, на основе user story. Это не вся инфа, но база эксплуатационной документации.
Но комментарии кода с этим вообще не пересекаются.
Иногда по ГОСТ требуют проектную документацию, и это ближе к комментариям, но тоже зачастую другое...

0