Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились.
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
А писать понятный код не получается? Ну комментарии можешь для себя писать, но понятный код это обязательное условие по сути. А то бывает смотришь код, а там перменные а1, а2, а3 и к ним комментарии. А нельзя их обозвать более понятно и не пистаь комментарий?
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны. G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились. G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Имхо, нужно обязательно ссылаться на алгоритмы (если они нетривиальные) со ссылкой на работу и кратким описанием.
Для понимания некоторых кусков иногда полезны ссылки на документацию по платформе.
Разные оптимицазии и кулхацкерные трюки, и пр.
А просто так комментариев лучше избегать. Особенно бесят тавтологичные комментарии:
GetUserName() // Getting user name
Потом такое через доксиджен в документацию попадает
Читаешь и цокаешь языком: "Надо же, кто бы мог подумать"
Модератор-националист Kerk преследует оппонентов по политическим мотивам.
на форуме есть один русский американец, которому кроме комментарий к коду еще требовал специалиста который бы ему еще разжевал что как и где нужно
а вообще вопрос поставлен не правильно...
если вопрос про документирование кода
после которого натравливаются всякие автодоки итд
которые формируют хрень на html
ну типа того же reactos можно найти в гугле
или много всяких опенсоус проектов
где комментируют каждую строчку
то я категорически против
особенно противно читать код в котором >60% комментариев
я за комментарии в скользких моментах которые сложно понять даже вникнув и разобравшись в коде
и таких комментариев на модуль не должно превышать 1% от всего кода
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны. G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились. G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Коментировать не нужно, нужны типовые примеры использования, вменяемая документация где описаны область применения и заложенные ограничения и ссылки где искать нужные детали если всё же кто-то полезет внутрь.
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
Демагогическое враньё из нефальсифицируемых утверждений. Вот как например проверить, "комментирует себя сам" или нет? G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились. G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
У вас что, цель "быть как все"?
Нужно исходить из вашей стратегии, и из того, насколько у вас солидарное общество.
Если вам пойдёт на пользу облегчить коллегам будущую работу с этим кодом — то: код не содержит целую кучу информации (зачем его писали именно так, с учётом каких обстоятельств вне этого куска кода), и хорошо бы это зафиксировать в комментариях.
Если кругом враги, которые получат премию за ваш счёт — тут понятно, пусть сами затрачивают весь труд, который пришлось затратить вам на выяснение того что [было бы] в комментариях
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны. G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились. G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Ну как, во всем нужен баланс
Не нужно комментировать вещи, которые и так очевидны если посмотреть на код.
Вещи, которые не очевидны, комментировать все еще нужно.
То есть, хорошие комментарии должны скорее отвечать не на вопрос "как" (это должно быть понятно из кода) или "что это" (должно быть понятно из названия), а на вопрос "зачем это", или "почему именно так, а не иначе".
Еще вариант, когда (даже тупые) комментарии нужны, это когда они например используются для автоматической генерации документации для пользователя (который не работает в вашей компании)
Здравствуйте, Denwer, Вы писали:
D>А то бывает смотришь код, а там перменные а1, а2, а3 и к ним комментарии. А нельзя их обозвать более понятно и не пистаь комментарий?
Для GO а1, а2, а3 — это стандартный подход.
"For every complex problem, there is a solution that is simple, neat,
and wrong."
Здравствуйте, gress, Вы писали:
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Мне известны следующие случаи.
Код.
1) Не комментировать код.
В этом случае код чист от отвлекающих комментариев не имеющих отношения к работоспособности. На его анализ не затрачивается время.
2) Обычные комментарии в коде.
Могут быть написаны как угодно и кем угодно, особенно разными людьми. Делают код грязным, то есть ухудшают анализ кода и могут не соответствовать действительности.
3) Самодокументируемый код.
Так же делает код грязным, но позволяют сгенерировать документацию. Благодаря объёму ещё больше отвлекает от анализа кода. Вопрос ещё и в том, кто пишет код, а кто пишет документацию.
Документация.
1) Отсутствует.
В реальности комментарии внутри кода это жалкая попытка заменить отсутствие документации.
2) Присутствует.
В документации можно описать принцип работы, вставить чертежи, объяснить отброшенные варианты. И нет, код сам себя не описывает.
Что выбрать
Для себя можно писать комментарии, например, на русском или как делают германцы на германском, но стоит ли загрязнять код в общем проекте. Те кто думают, что написав комментарии на английском чем-то помогли и обманули систему лучше задумайтесь о понятном именовании и конструировании.
Системы самодокументирования могут располагать документацию не только в коде, но и в отдельных файлах. То есть код будет чист, при том, что документацию всё равно можно будет сгенерировать.
По идее у проекта должны быть прописаны соглашения об оформлении кода. Опять же есть программы, которые могут менять оформление кода автоматически.
Лично мне было бы приятнее видеть код без комментариев, но с подробной внешней документацией. Но тогда следующий спор пойдёт о том, нужно ли писать документацию, которая устаревает быстрее, чем программисты говнокодят, и если нужно, то кому.
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
Люди в команде читают код коллег? Вот кто-то запилил пулл-реквест (чейнджсет), коллеги просто так туда заглянут? Если нет, значит комментарии нужны, ибо читать чужой и свой код и понимать его — это навык, который надо постоянно развивать.
G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились. G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Я комментирую кусок сложного алгоритма, который я пока ещё не знаю как превратить в код. Потом постепенно комментарии дополняются кодом, многие комментарии выживают и остаются. А вообще я свой код мало комментирую и иногда страдаю от этого, когда мне же самому надо разобраться в своём коде, который я написал пару лет назад. Мне помогает только та самая привычка читать и перечитывать код, я всегда могу разобраться.
С практической точки зрения, надо кратко описывать публичные классы и их методы, внешние процедуры и функции, структуры данных. То есть, весь тот код, на который будут смотреть другие.
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
Комментарии нужны там где они нужны и вредны там где они не нужны. Прямо в коде комментировать нужно нетривиальные (не очевидные рандомному девелоперу) алгоритмические штуки, которые выполняет код. Комментировать нужно назначение и (не очевидные) сценарии использования функций/классов.
Комментарии в стиле тут мы складываем a и б а тут вычитаем — не нужны, а значит — вредны.
Отдельный вред представляют собой misleading комментарии, то есть когда в комменте одно, а код делает другое. Это вот — самое большое зло, которое может быть от комментов. Такое бывает после изменений, ведь комменты автотесты не фэйлят)
Как много веселых ребят, и все делают велосипед...
Здравствуйте, velkin, Вы писали:
V>Лично мне было бы приятнее видеть код без комментариев, но с подробной внешней документацией. Но тогда следующий спор пойдёт о том, нужно ли писать документацию, которая устаревает быстрее, чем программисты говнокодят, и если нужно, то кому.
Самодокументируюющийся код — это утопичная идея, что надо такие выбирать названия для всех идентификаторов, чтобы сразу было понятно, что делается. Конечно, желательно стараться писать понятнее, но так гладко не бывает на практике: или алгоритм нетривиальный или какой-то трюк или просто правильное наименование замусорит экран.
Внешняя документация — это здорово, но для ее написания нужны лишние телодвижения, а комментарии в коде пишутся по ходу работы мысли. Никогда не сталкивался с тем, что спустя пару лет (а то и пару месяцев) смотришь на код, который сам же писал и вообще не врубаешься?
Поэтому мне комментарии в коде помогают. Разумеется тривиальные комментарии делать бессмысленно и даже вредно из-за замусоривания, но поясняющие идеи, которые стоят за кодом, практически обязательно необходимы.
Здравствуйте, Michael7, Вы писали:
M>Самодокументируюющийся код — это утопичная идея, что надо такие выбирать названия для всех идентификаторов, чтобы сразу было понятно, что делается. Конечно, желательно стараться писать понятнее, но так гладко не бывает на практике: или алгоритм нетривиальный или какой-то трюк или просто правильное наименование замусорит экран.
Самодокументируемый код это системы вроде Doxygen и другие. Для примера Qt использует эту технологию. Суть в том, что документация прописывается прямо в коде в виде комментариев в особом формате, например, над классом или методом. Но не обязательно, можно просто указать название класса или метода, а саму документацию разместить в другом файле.
Исходный код.
/*!
Constructs an object with parent object \a parent.
The parent of an object may be viewed as the object's owner. For
instance, a \l{QDialog}{dialog box} is the parent of the \uicontrol{OK}
and \uicontrol{Cancel} buttons it contains.
The destructor of a parent object destroys all child objects.
Setting \a parent to 0 constructs an object with no parent. If the
object is a widget, it will become a top-level window.
\sa parent(), findChild(), findChildren()
*/
QObject::QObject(QObject *parent)
: d_ptr(new QObjectPrivate)
{
Q_D(QObject);
d_ptr->q_ptr = this;
d->threadData = (parent && !parent->thread()) ? parent->d_func()->threadData : QThreadData::current();
d->threadData->ref();
if (parent) {
QT_TRY {
if (!check_parent_thread(parent, parent ? parent->d_func()->threadData : 0, d->threadData))
parent = 0;
setParent(parent);
} QT_CATCH(...) {
d->threadData->deref();
QT_RETHROW;
}
}
#if QT_VERSION < 0x60000
qt_addObject(this);
#endif
if (Q_UNLIKELY(qtHookData[QHooks::AddQObject]))
reinterpret_cast<QHooks::AddQObjectCallback>(qtHookData[QHooks::AddQObject])(this);
}
Здравствуйте, gress, Вы писали: G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
просто любой код развивается. и приходится держать комменты и код в синхроне. а так как людям своейственно ошибаться, то комменты могут ввести в заблуждение. плюс если дать человеку задачу писать код без комментов надо быть большим дураком, чтобы использовать идентификаторы типа bzl и давать понятные самообьясняющие имена.
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам.
Новым? У этого веяния уже борода до пупа.
G>Так как я боец старой формации, для меня это дикость.
Дикость, да.
Но идеал посередине: код должен быть максимально понятный а комменты надо писать к логическим блокам, разъясняя что мы тут делаем на high level и нафига.
Ну есессна более сложные места должны быть более детально комментированы. Особенно там, где что то делаем вынужденно.
G> Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились.
А, ну тогда это проще: в разработке нет места демократии, только диктатура.
Здравствуйте, reversecode, Вы писали:
R>если вопрос про документирование кода после которого натравливаются всякие автодоки итд которые формируют хрень на html
В результате автогенерируется документация Капитана Очевидности, которая бесполезна чуть более чем полностью.
Отличный пример правильной документации был старый MSDN — где было нормальным языком написано что, как, и нахрена.
R>или много всяких опенсоус проектов где комментируют каждую строчку
Это совсем маразм, да
R>то я категорически против
+1
R>особенно противно читать код в котором >60% комментариев
Почти невозможно.
R>я за комментарии в скользких моментах которые сложно понять даже вникнув и разобравшись в коде
+100500
R>и таких комментариев на модуль не должно превышать 1% от всего кода
Если такого много то это значит что весь код довольно говёный, да.
Здравствуйте, velkin, Вы писали:
V>Самодокументируемый код это системы вроде Doxygen и другие.
Нет. Это тупиковая ветка развития, которая только замусоривает код.
Здравствуйте, velkin, Вы писали:
V>Здравствуйте, Michael7, Вы писали:
M>>Самодокументируюющийся код — это утопичная идея, что надо такие выбирать названия для всех идентификаторов, чтобы сразу было понятно, что делается. Конечно, желательно стараться писать понятнее, но так гладко не бывает на практике: или алгоритм нетривиальный или какой-то трюк или просто правильное наименование замусорит экран.
V>Самодокументируемый код это системы вроде Doxygen и другие. Для примера Qt использует эту технологию. Суть в том, что документация прописывается прямо в коде в виде комментариев в особом формате, например, над классом или методом. Но не обязательно, можно просто указать название класса или метода, а саму документацию разместить в другом файле.
Хм, какая-то путаница в терминах. Я под тем, что ты сказал понимал, автогенерацию документации и тп., а самодокументируемый код — нечто другое, например, такое: https://habr.com/ru/post/458264/
10 принципов самодокументируемого кода
1. Пишите простой код с хорошим форматированием
2. Выбирайте осмысленные имена
3. Разбивайте код на самостоятельные функции
4. Выбирайте содержательные имена типов
5. Применяйте именованные константы
6. Выделяйте важные фрагменты кода
7. Объединяйте взаимосвязанные данные
8. Снабжайте файлы заголовками
9. Правильно обрабатывайте ошибки
10. Пишите осмысленные комментарии
