Здравствуйте, 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. Пишите осмысленные комментарии
Здравствуйте, Michael7, Вы писали:
M>Хм, какая-то путаница в терминах. Я под тем, что ты сказал понимал, автогенерацию документации и тп., а самодокументируемый код — нечто другое, например, такое: https://habr.com/ru/post/458264/
Ну вот смотри, что пишет пользователь хабра.
Привет! Сегодня я хочу поделиться советами по написанию совершенного понятного кода, взятые из книги Питера Гудлифа «Ремесло программиста // Практика написания хорошего кода».
А теперь я открываю эту книгу.
Техника написания самодокументируемого кода
Обычно считается, что самодокументируемый код должен содержать в себе обилие комментариев. Хорошие комментарии, несомненно, нужны, но ими дело не ограничивается. На самом деле нужно стремиться избегать комментариев путем написания такого кода, в котором в них нет необходимости.
В моём понимании, если для кода нет документации, то это недокументируемый код. Сам Питер Гудлиф пишет, что самодокументируемый код должен содержать в себе обилие комментариев, просто они должны нести смысл. Другое дело для одних комментарии в стиле псевдокода не имеют смысла, а для других является важной частью документации.
Или вот он пишет.
Снабжайте файлы заголовками
Помещайте в начале файла блок комментариев с описанием содержимого файла и проекта, к которому он относится. Это не требует особого труда, но приносит большую пользу. Тот, кому придется сопровождать этот файл, получит хорошее представление о том, с чем он имеет дело.
Этот заголовок может иметь особое значение: большинство софтверных компаний по юридическим соображениям требует, чтобы в каждом файле с исходным кодом было заявление об авторских правах. Обычно заголовки файлов выглядят примерно так:
/*********************************************************
* File: Foo.java
* Purpose: Foo class implementation
* Notice: (c) 1066 Foo industries. All rights reserved.
********************************************************/
И далее.
Инструментарий документирования
Существует целый вид программных средств, занимающих промежуточное положение между технологией грамотного программирования и созданием внешних спецификаций. Эти инструменты генерируют документацию из исходного кода, вытаскивая из него блоки особым образом форматированных комментариев. Особенно модной такая техника стала после того, как Sun ввела Javadoc в качестве базовой компоненты платформы Java. Вся документация Java API генерируется с помощью Javadoc.
Чтобы лучше разобраться в том, как это работает, рассмотрим пример. Формат комментариев может немного отличаться, но в принципе документирование класса Widget осуществляется так:
/**
* Это документация класса Widget.
* Программа определяет начало комментария
* с помощью особой последовательности '/**' .
*
* @author Имя автора
* @version Номер версии
*/
class Widget
{
public:
/**
* Здесь документируется метод.
*/
void method();
};
Это всё раздел самодокументируемого кода.
4. Литературоведение 93
Самодокументируемый код 95
Техника написания самодокументируемого кода 98
Практические методологии самодокументирования 103
Резюме 108
Контрольные вопросы 109
Я просто пояснил как именно я понимаю самодокументируемый код. Если документация прямо в коде, то код самодокументируемый, а если в отдельном файле, то нет. А обычные комментарии я не считаю за документацию и документирование, так как на мой взгляд документация должна иметь формат и шаблон, а не являться случайными записями.
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились.
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
От многих факторов зависит стоит ли это делать:
1. ЯП. если типа C++ то наверно стоит.
2. от ресурсов. если ресурсов(человеко-часов) много то наверно стоит.
3. если код долгое время не актуализровался, не трогался можно оставить хлебные крошки чтобы разобраться быстрее при необходимости.
4. если нет носителя знаний о коде.
5. если нет нормального ТЗ/ТТ с таблицей вариантов использования. то же можно.
PS возможно от вас просто ждут решения, топнуть ногой и сказать пишите.
Идея. на кодревью если непомнятно попросить дописать коммент. истина где-то посередине.
Вообще-то при разработке чего-то е совсем уж тривиального, я сначала пишу комментарий, чего и в каком порядке надо делать.
Если после написания коммента понятно, что и как — пишу ниже код.
Если нет, раскрываю коммент в несколько строк более детальных действий
И так далее.
Точно, как рекомендовал Никлаус Вирт — пошаговое уточнение.
Как-то хорошо мне упало.
Своим студентам неоднократно демонстрировал, как это делается.
Однажды надо было на C# в нашей IDE написать что-то в меню по работе с файлами.
Спрашиваю у нашего разработчика главного, чего делать, и пишу прямо комментами.
Потом посмотрел, уточнил.
Написал код по комментам.
Разработчик, мой студент, офигел: я написал, а оно СРАЗУ работает...
Неоднократно студентам показывал, что наличие комментов сильно облегчает последующие возвраты к старым кускам,
которые надо как-то в новом контексте использовать.
Я с 2011 до 2018 писал проги по моделированию процесса перколяции. Где я и где перколяция...
Писал в процедурном стиле по требованию заказчика.
Потом подставил вместо себя своего выпускника.
Он новые проги, естественно, не комментировал — типичное поведение джуна.
Типа и так же помню...
Но когда он мне принес посмотреть, так как у него чего-то не получалось, выяснилось, что он нифига не помнит, почему он написал так, а не иначе.
Уже через 2 недели нифига не помнит.
А я ему через 7-10 лет показываю прогу и рассказываю, что там написано и почему.
И зачем нужна каждая переменная.
И сейчас могу.
Комменты — это письма к себе.
Если же прога одноразовая, то можно и не писать.
Хочешь быть счастливым — будь им!
Без булдырабыз!!!
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились.
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
У нас правила такие:
Код комментирует сам себя, но в разумных пределах.
Например, не стоит называть метод слишком длинно в попытке "откомментировать самого себя", типа getFileNamesOrDirectoriesOrThrowExceptionAndLogItAndSendJMSMessageAndAskForDeletion(), это, очевидно, перебор.
Также функциональный стиль неплохо дружит с самодокументируемостью, т.к. функции, даже мелкие, можно называть самодокументируемо (в книге Бэнкса по Реакту есть отличные примеры того, как писать самодокументируемый функциональный код).
Комментарии писать тоже нужно, как раз там, где код остается неочевидным или непонятным, используется какая-то черная магия (хотя черную магию лучше избегать вовсе), костыли и т.д.
Также комментарии имеет смысл писать на TODO для техдолга. В тикеты заводить все техдолги — геморно, а TODO парсятся тем же плагоном дженкинса, позволяя видеть динамику TODO и контролировать тем самым техдолг.
Очевидные комментарии, комментарии ради комментариев — никому не нужны и только засоряют код и затрудняют его рефакторинг (попробуй синкать обильные комменты при рефакторинге — замучаешься).
Также комменты важны в публичном АПИ для описания контракта, хотя и тут в Джаве есть богатый набор аннотаций на все случаи жизни, типа что класс потокобезопасный, параметры nullable и т.д. — всё это можно сделать через аннотации, чем через комментарии. И аннотации лучше, т.к. позволяют подключать инструменты проверки выполнения контракта.
Здравствуйте, AndrewJD, Вы писали:
D>>А то бывает смотришь код, а там перменные а1, а2, а3 и к ним комментарии. А нельзя их обозвать более понятно и не пистаь комментарий? AJD>Для GO а1, а2, а3 — это стандартный подход.
Если это локальные переменные и код короткий, то это нормально.
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
Срач древний, как продукты жизнедеятельности мамонтов.
И всегда большинство спорщиков делятся на 2 лагеря, где успешно при молении своим богам разбивают лбы об пол.
Бессмысленные комментарии не нужны, осмысленный и нужные комментарии нужны. Проверка осмысленности и нужности — понять свой код через полгода.
Ну лично я считаю, что всё, что можно прокомментировать кодом, то бишь названиями идентификаторов или юнит-тестами, нужно стараться делать именно так, т.е. избегать комментариев там, где это можно.
Комментарии нужны, но для более нетривиальных вещей, которые невозможно выразить в коде.
Здравствуйте, Vzhyk2, Вы писали:
V>Бессмысленные комментарии не нужны, осмысленный и нужные комментарии нужны. Проверка осмысленности и нужности — понять свой код через полгода.
Более быстрый способ проверки — через код ревью. Если ревьюверу код непонятен, даже вкупе с предоставленным юзер стори по фиче или с тикетом, значит нужно что-то делать: улучшать структуру, названия программных сущностей, добавлять комментарии.
Здравствуйте, gress, Вы писали:
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
комментарии нужны чтобы сделать код читабельным и поддерживаемым, если без комментариев можно разобраться в том зачем и как делает код — комментарии не нужны, иначе — нужны. Обычно это "можно разобраться или нет" видно на код-ревью. Обычно никто сейчас комментарии не пишет, разве что если хинты, т.к. в подавляющем большинстве случаев логика достаточно тривиальна, например конвертация/адаптация данных из одного слоя/домена в другой. Но если логика не тривиальна или если из низкоуровневых деталей реализации сложно восстановить оригинальный посыл (например алгоритм часто можно описать парой-тройкой предложений, но реализация будет просто набором мат. операций), то конечно комментарии нужны. Но опять же, это всё видно на код-ревью.
Здравствуйте, CreatorCray, Вы писали:
CC>Но идеал посередине: код должен быть максимально понятный а комменты надо писать к логическим блокам, разъясняя что мы тут делаем на high level и нафига.
На вопрос "нафига" должен git blame и комментарий в коммите отвечать, в котором должно быть куда больше контекста.
Здравствуйте, CreatorCray, Вы писали:
CC>Здравствуйте, reversecode, Вы писали:
R>>если вопрос про документирование кода после которого натравливаются всякие автодоки итд которые формируют хрень на html CC>В результате автогенерируется документация Капитана Очевидности, которая бесполезна чуть более чем полностью.
пример автосгенеренной (как утверждается) документации http://ceres-solver.org/ . Понятно для любого ученика церковно-приходской школы.
Здравствуйте, gress, Вы писали:
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Комментарии должны быть уместными, комментировать код: GetUserContext() — не надо, и так все понятно.
Но еесли в коде GetUserNFContext() — и нет глоссария, что за такой NF, то можно и написать комментарий.
Так, же комментарий нужен к алгоритму/расчету данных.
И комментарии не должны заменять правильно именованные константы и переменные.
Здравствуйте, gress, Вы писали:
g> Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
Есть такое. Видел даже как комментарии специально удаляются из кода ради культа "самодокументирующегося кода".
g> Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
По статистике большинство разработчиков комментируют свой код, только об этом не принято вот так публично рассказывать А если серьезно, то я еще не видел хорошего кода без комментариев.
Здравствуйте, gress, Вы писали:
G>Так как я боец старой формации, для меня это дикость.
Насколько старой? Мне в конце 90-х в универе втирали про самодокументирующийся код. А потом прогрессивные коллеги на работе дошлифовывали втертое.
Здравствуйте, Skorodum, Вы писали:
S>Даже для API примеры и тесты важнее.
я это не отрицаю, но обычно апи меняется редко и там формальное описание имеет смысл, все равно оно существует если не в коде то в документации для использования
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Мне тоже это постоянно говорят, но проблема даже не в этом. А в том, есть системы *взять из базы и положить в базу*, где это особо не нужно (хотя бывают исключения, если там какая-то обработка всё же имеется нетривиальная) и есть такие, где 99% математики и статистики и там уже на второй строке ничего не понятно "рядовому программисту". И даже не рядовому.
Я уже не говорю про всякие хаки, магические числа и строки и т.п.
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
почему бы, прежде чем задавать такие вопросы, не почитать что-то для начала? тот же "чистый код" Мартина, разобраться что такое code smells. глядишь, и противоречий в команде станет меньше.
Здравствуйте, Ватакуси, Вы писали:
В>Я уже не говорю про всякие хаки, магические числа и строки и т.п.
Да. Имеет смысл комментировать те вещи, которые невозможно выяснить из кода.
Например то, что не должно случиться или появиться при любых обстоятельствах.
Что некоторая константа никогда не должна быть равна нулю, например.
Или вон в Unicode стандарт гласит, что определённые диапазоны кодовых точек являются запрещёнными к применению. И никогда, ни в каких версиях стандарта, впредь они не встретятся.
Комментировать также стоит пути развития и расширения системы. Ты сейчас в коде этого не увидишь, но можно написать — что, как и где должно меняться, чтобы добавить новые возможности.
Просто это неочевидно бывает. А люди, которые будут после тебя работать над твоей программой, не телепаты, и твои мысли и соображения прочесть не смогут.
Могут начать что-то делать, и пойдут не в ту степь. Иногда ты потом сам открываешь и читаешь, что другие люди наворотили. В ужас приходишь, насколько всё испортили.
UPD: Вот ещё вспомнил. Комментировать надо такие вещи, как карта памяти. Какие диапазоны адресов для чего предназначаются. Это всё из кода так просто не выяснишь.
Ну и разумеется, всякие нетривиальные моменты. Замысловатые трюки, хаки. Сложную функциональность.
Вот скажем, если у нас есть интерпретатор какого-то скриптового языка. Этот язык, разумеется, следует задокументировать. По коду интерпретатора понять, что за язык, его синтаксис — дело очень и очень непростое.
Форматы конфигурационных файлов, сетевые протоколы. Да даже просто форматы бинарных файлов — тоже стоит документировать.
Здравствуйте, denisko, Вы писали:
D>пример автосгенеренной (как утверждается) документации http://ceres-solver.org/ . Понятно для любого ученика церковно-приходской школы.
А где там документация? Кинь прямую ссылку а то лень лазить и искать что ты там имел в виду.
Здравствуйте, Skorodum, Вы писали:
S>На вопрос "нафига" должен git blame и комментарий в коммите отвечать, в котором должно быть куда больше контекста.
Нет. Потому что тебе придётся читать много коммитов предварительно "смержив" их содержимое.
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
Собственно код, без комментариев, должен 100% давать ответ на вопрос "что здесь делается". Если из структуры кода это не понятно, то его надо рефакторить.
Комментарии должны отвечать на вопрос "зачем это делается" и "на что обратить внимание, меняя это код в будущем" там, где это критично.
Чтобы не быть голословным, пример плохого комментария:
Комментарий "Set device registers" бесполезен. Если хочется вынести вызовы set_register() в отдельный смысловой блок, это надо делать через отдельный метод, благо оптимизатор, если надо, заинлайнит это с нулевым оверхедом:
С другой стороны, вот пример хорошего комментария:
inline void SetDeviceRegisters(Context context)
{
set_register(REG_A, context.A);
set_register(REG_B, context.B);
//Clearing PERIPHERAL_BUS_ENABLED would prevent the device from responding
//to subsequent commands until the user physically resets it.
//See section 6.66 on page 420 in datasheet revision 13.
//Hence, we always keep this bit on as a precaution.
//WARNING: this bit is hardware-specific and should be updated when porting
//to different hardware.
set_register(REG_C, context.C | PERIPHERAL_BUS_ENABLED);
}
Здравствуйте, Quebecois, Вы писали:
Q>Если хочется вынести вызовы set_register() в отдельный смысловой блок, это надо делать через отдельный метод
Нет, не надо. В данном случае это только усложнит читабельность кода, потому что придётся куда то ещё по коду лазить чтоб увидеть какие то сраные три строки которые больше нигде никогда не используются.
Здравствуйте, CreatorCray, Вы писали:
CC>Здравствуйте, Quebecois, Вы писали:
Q>>Если хочется вынести вызовы set_register() в отдельный смысловой блок, это надо делать через отдельный метод CC>Нет, не надо. В данном случае это только усложнит читабельность кода, потому что придётся куда то ещё по коду лазить чтоб увидеть какие то сраные три строки которые больше нигде никогда не используются.
С тремя строками — да, их мозг абстрагирует в любом случае. Если же там будет что-то сложнее (скажем, определение текущего режима, и чтение разных наборов регистров в зависимости от него) — то ему самое место в отдельном методе. Потому что сложная сущность "прочесть mode, а потом или X+Y+Z, или A+B, или C/D в зависимости от E" заменяется простой "сохранить снапшот устройства в переменную". Отдельным плюсом — будет явный data flow (что на входе, что на выходе, что — временная переменная).
Но подобные вещи жутко субъективны, потому что количество оперативки в мозгах у все людей разное, и понимание об оптимальном уровне абстракции — тоже. Поэтому, я бы это применял только для вариантов, где реально вся логика метода не помещается в голову за один раз.
Здравствуйте, Quebecois, Вы писали:
CC>>Нет, не надо. В данном случае это только усложнит читабельность кода Q>С тремя строками — да, их мозг абстрагирует в любом случае.
О чём и речь.
Q> Если же там будет что-то сложнее (скажем, определение текущего режима, и чтение разных наборов регистров в зависимости от него) — то ему самое место в отдельном методе.
Это верно.
Q>Но подобные вещи жутко субъективны, потому что количество оперативки в мозгах у все людей разное, и понимание об оптимальном уровне абстракции — тоже. Поэтому, я бы это применял только для вариантов, где реально вся логика метода не помещается в голову за один раз.
Ну дык серебряной пули ж нету, потому не надо задавать уж совсем жёсткие условия в строках и т.п.
А вообще скилл хорошего оформления приходит с опытом. Чем больше собственноручно насранного говнокода перелопатишь тем аккуратнее начинаешь писать.
Здравствуйте, gress, Вы писали:
G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились. G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Каменты имеют свойство рассинхронизироваться с тем кодом для которого они писались. Например, автоматический рефакторинг "переименовать+заинлайнить" оставит все каменты и мы получим хрень. Требовать рефакторить вручную или запрещать рефакторинг мягко говоря неразумно.
Итого
1. для генерации доков в паблик членах давать краткое описание, что за свойство-функция-параметры и какието вспомогательные вещи типа
"эта фукнция тригерится в том случае, когда приходит вот такой реквест + пример реквеста"
2. неочевидные проблемы, например конвеншн — использовать const enum по умолчанию. Но исключения — документировать export /*const*/ enum Handles { /*const enum will break the previously published packages*/ т.к. покрыть такое тестами затруднительно.
3. мотивацию выбора решения — "в xxx суппортим только тип Строка, т.к. дсл пока что не поддерживает ничего другого"
4. кастомные алгоритмы, эвристики не стоит покрывать тестами, вместо этого стоит писать легко-читаемый код.
Кроме того, вместо всяких мутных и лишних каментов стоит использовать Guard, Assert, Invariant, Verify, Validate, Schema и подобные вещи. Например
if(meta.isArray()) {
Assert.isArray(input); // и здесь не надо писать камент "вот тут у нас должен быть массив"
return input.map(x => ...)
}
Здравствуйте, denisko, Вы писали:
D>пример автосгенеренной (как утверждается) документации http://ceres-solver.org/ . Понятно для любого ученика церковно-приходской школы.
Здравствуйте, gress, Вы писали:
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Это последствия встречи журналистких технологий с неокрепшими мозгами. Статьи "отдыхать лучше, чем работать" всегда будут в топе.
"комментировать или нет" — это неформализуемое экспертное знание, т.к., очевидно, нужно писать полезные комментарии и не писать бесполезные. Еще одно очевидно-бесполезное правило — комментарии должны содержать то, чего нет в коде или что извлечь из кода непросто.
Любителям "не писать комментарии" можно предложить описать смысл полей доменной модели, которую разрабатывали не они. Рассуждающие о "код должен документироваться тестами" никогда тесты не читали. Хаскелисты с "поведение функции можно полностью определить её сигнатурой" пусть снчала расскажут, откуда внимательный читатель узнает смысл всех типов в этой сигнатуре. Еще доводы "за":
— обход бага в фреймворке/библиотеке/ОС. Без комментария практически невозможно понять такие нелогичные кусочки кода
— алгоритмы и сложная бизнес-логика
— банальное уважение к рабочему времени членов команды — прочитать комментарий над классом или методом значительно быстрее, чем изучать реализацию
Здравствуйте, Quebecois, Вы писали:
Q>[ccode]inline void SetDeviceRegisters(Context context) Q>{ Q> set_register(REG_A, context.A); Q> set_register(REG_B, context.B); Q> //Clearing PERIPHERAL_BUS_ENABLED would prevent the device from responding Q> //to subsequent commands until the user physically resets it. Q> //See section 6.66 on page 420 in datasheet revision 13. Q> //Hence, we always keep this bit on as a precaution.
Раз уж bikeshedding (хотя и так нормально)
Clearing PERIPHERAL_BUS_ENABLED prevents the device from responding
to commands until physical reset so keep it set, see
section 6.66 "Supabit for not responding" in the "USB XHCI" specification.
"would", "hence", "user" не нужно (меня много слов расстраивает), а нужны точные слова из спеки чтоб по ней поиском находились. Хотя название бита довольно говорящее.
Q> //WARNING: this bit is hardware-specific and should be updated when porting Q> //to different hardware. Q> set_register(REG_C, context.C | PERIPHERAL_BUS_ENABLED);
Добавить префикс типа INTEL_XHCI_PERIPHERAL_BUS_ENABLED, и комментарий не нужен.
Здравствуйте, aik, Вы писали:
aik>"would", "hence", "user" не нужно
Мне "therefore" тоже больше нравится чем "hence"
Пусть будут, задачи сэкономить буковки в комментах никогда не стояло, более того, народ комменты часто пишет точно так же как бы они объясняли сие словами, т.е. просто записывают прямую речь.
G>Более быстрый способ проверки — через код ревью. Если ревьюверу код непонятен, даже вкупе с предоставленным юзер стори по фиче или с тикетом, значит нужно что-то делать: улучшать структуру, названия программных сущностей, добавлять комментарии.
Тоже хороший вариант.
Здравствуйте, Skorodum, Вы писали:
S>Здравствуйте, CreatorCray, Вы писали:
CC>>Нет. Потому что тебе придётся читать много коммитов предварительно "смержив" их содержимое. S>Зачем много?
Потому что у проектов над которыми долго работает много людей часто бывает что чуть ли не у каждой строки отдельный коммит.
Так что blame покажет тебе мелко нашинкованные коммиты и до исходного коммита придётся продираться через эти наслоения.
Здравствуйте, CreatorCray, Вы писали:
CC>Потому что у проектов над которыми долго работает много людей часто бывает что чуть ли не у каждой строки отдельный коммит.
Абсолютно неважно какого размера проект и сколько людей над ним работет. Один коммит решает одну логическую задачу. Может быть изменена одна строчка, а может быть 1000. Если вы по сообщению коммита изменившего строчку не можете понять почему и зачем, то ваши коллеги сделали плохой коммит.
CC>Так что blame покажет тебе мелко нашинкованные коммиты и до исходного коммита придётся продираться через эти наслоения.
А можно правильно использовать гит
Здравствуйте, Skorodum, Вы писали:
S> Один коммит решает одну логическую задачу.
Коммит то задачу решает, вот только при этом трогает много строк в многих файлах.
И когда у тебя кодобаза чуть ли не с 90х тянется там такое лоскутное одеяло за это время набирается.
S>Если вы по сообщению коммита изменившего строчку не можете понять почему и зачем
Ты одну строчку читаешь или таки всю функцию где есть эта строчка?
Так что придётся собрать кучу коммитов из которых состоит эта функция, а также предыдущих коммитов и читать их все.
Потому как последним коммитом для строки может быть что то, что меняет только небольшой кусочек в ней, и чтоб найти изначальный смысл надо протрекать строку до куда более существенного коммита.
Так что не работает такой подход.
Здравствуйте, CreatorCray, Вы писали:
CC>И когда у тебя кодобаза чуть ли не с 90х тянется там такое лоскутное одеяло за это время набирается.
И в чем проблема-то?
1. Если никак решить задачу изменениями в одном файле, меняются несколько
2. Если попутно надо что-то отрефакторить, оно рефакторится и коммится отдельно, потом основаная задача отдельным коммитом.
CC>Ты одну строчку читаешь или таки всю функцию где есть эта строчка? CC>Так что придётся собрать кучу коммитов из которых состоит эта функция, а также предыдущих коммитов и читать их все.
Да не придется, изменения в логике не могут быть разбиты на несколько коммитов, т.к. тогда коммиты будут не рабочие.
Ну а если вы делаете такие коммиты — то сами себе злобные буратины
CC>Потому как последним коммитом для строки может быть что то, что меняет только небольшой кусочек в ней, и чтоб найти изначальный смысл надо протрекать строку до куда более существенного коммита.
По git blame сразу видно, какой коммит изменил больше всего
Единственное коммит типа "Fix format" может "скрыть" реальную историю.
CC>Так что не работает такой подход.
Вот навскидку: давай взглянем на ядро линухи из 90-х. Найди там описанную тобой проблему.
Здравствуйте, Skorodum, Вы писали:
CC>>И когда у тебя кодобаза чуть ли не с 90х тянется там такое лоскутное одеяло за это время набирается. S>И в чем проблема-то?
Попробуй прочитать ещё раз.
S>1. Если никак решить задачу изменениями в одном файле, меняются несколько
Спасибо Кэп!
S>2. Если попутно надо что-то отрефакторить, оно рефакторится и коммится отдельно, потом основаная задача отдельным коммитом.
Это никак не помогает уменьшить лоскутность blame для того, кто будет смотреть на полный файл через год?
S>Да не придется, изменения в логике не могут быть разбиты на несколько коммитов, т.к. тогда коммиты будут не рабочие.
Да лехко
Добавляется логика которая пока не используется вне тестов или вовсе compiled out
S>По git blame сразу видно, какой коммит изменил больше всего
И как git blame заставить показать коммит 5летней давности, почти все строки которого были за это время потроганы сотней других коммитов?
У p4 был отличный тул timelapse, который позволял ходить по истории туда-сюда в наглядном виде и видеть что происходило в конкретном range строк.
Git так не умеет. Можно только врукопашку.
CC>>Так что не работает такой подход. S>Вот навскидку: давай взглянем на ядро линухи из 90-х. Найди там описанную тобой проблему.
У меня нет ни времени ни желания смотреть на ядро линуха.
Здравствуйте, CreatorCray, Вы писали:
CC>Здравствуйте, Skorodum, Вы писали:
CC>>>И когда у тебя кодобаза чуть ли не с 90х тянется там такое лоскутное одеяло за это время набирается. S>>И в чем проблема-то? CC>Попробуй прочитать ещё раз.
Слова кончились? "Старые проект" само по себе ничего не значит. В чем проблема-то? В плохих коммитах? ССЗБ
S>>1. Если никак решить задачу изменениями в одном файле, меняются несколько CC>Спасибо Кэп!
Пожалуйста
S>>2. Если попутно надо что-то отрефакторить, оно рефакторится и коммится отдельно, потом основаная задача отдельным коммитом. CC>Это никак не помогает уменьшить лоскутность blame для того, кто будет смотреть на полный файл через год?
Да покажи где эту лоскутность-то на примере сложного кода который не очевиден и надо смотреть историю, так чтобы git blame не помог.
S>>Да не придется, изменения в логике не могут быть разбиты на несколько коммитов, т.к. тогда коммиты будут не рабочие. CC>Да лехко CC>Добавляется логика которая пока не используется вне тестов или вовсе compiled out
Да без проблем, только логическре изменение должно быт цельными или ССЗБ
CC>И как git blame заставить показать коммит 5летней давности, почти все строки которого были за это время потроганы сотней других коммитов?
Если были потраганы, значит логика изменилась
CC>У p4 был отличный тул timelapse, который позволял ходить по истории туда-сюда в наглядном виде и видеть что происходило в конкретном range строк. CC>Git так не умеет. Можно только врукопашку.
Это было бы полезное дополнение, согласен.
CC>У меня нет ни времени ни желания смотреть на ядро линуха.
Зато есть время на бла-бла-бла. Ты говоришь о проблеме, а привести пример этой проблемы в проекте где за коммитами более-менее следят — не можешь
Здравствуйте, Skorodum, Вы писали:
CC>>Попробуй прочитать ещё раз. S>Слова кончились? "Старые проект" само по себе ничего не значит. В чем проблема-то? В плохих коммитах? ССЗБ
В том что ты не понял про что тебе говорят.
S>Да покажи где эту лоскутность-то на примере сложного кода который не очевиден и надо смотреть историю, так чтобы git blame не помог.
Т.е. ты мне предлагаешь щас шарить по публичным репам чтоб найти тебе пример того, что ты на словах не понимаешь?
S>Если были потраганы, значит логика изменилась
Далеко не всегда изменения кардинально меняют логику. Например переименовали константу, что породило тьму лоскутных изменений но ничегошеньки в логике не поменялось.
S>Ты говоришь о проблеме, а привести пример этой проблемы в проекте где за коммитами более-менее следят — не можешь
Это несопоставимо по временным затратам.
Здравствуйте, LaptevVV, Вы писали:
LVV>Вообще-то при разработке чего-то е совсем уж тривиального, я сначала пишу комментарий, чего и в каком порядке надо делать. LVV>Если после написания коммента понятно, что и как — пишу ниже код. LVV>Если нет, раскрываю коммент в несколько строк более детальных действий LVV>И так далее.
Ну да, я понимаю, олд скул ))
По моей практике это сработает если
1) Очень сложная предметка и приходится описывать не то что ты делаешь а почему ты это делаешь.
2) Недружелюбный язык/платформа разработки. Например, в юности программировал однокристалки на c/asm, причем asm такой себе извращенный. И там действительно на строчку кода по пять строчек комментов бывало, ибо строчка, например, выставляет нолик или единичку на ножку процессора, а комментарий описывает, накой черт там этот нолик или единичка и куда и зачем потом пойдет.
Щас давно уже прочно сижу на .NET
И пишу лучше чем по-русски. То есть, когда пишу рядовой код, он оказывается проще для понимания и лаконичнее нежели мысль по древу на русском.
К тому же, код меняется постепенно и в самых разным местах. Ну то есть сделал мелочь, протестил, еще дописал, еще протестил и т.д. Параллельно рефакторить не только код но и комменты — ну его нафиг. Двойная работа.
Писать комменты считаю нужным только для чего-то, что с первого раза непонятно. И то, если такое место есть — то может его отрефакторить чтобы было понятнее?
Ну а если вообще никак — ну ок, пусть будут комменты.
G>Ну да, я понимаю, олд скул )) G>По моей практике это сработает если G>1) Очень сложная предметка и приходится описывать не то что ты делаешь а почему ты это делаешь. G>2) Недружелюбный язык/платформа разработки. Например, в юности программировал однокристалки на c/asm, причем asm такой себе извращенный. И там действительно на строчку кода по пять строчек комментов бывало, ибо строчка, например, выставляет нолик или единичку на ножку процессора, а комментарий описывает, накой черт там этот нолик или единичка и куда и зачем потом пойдет.
Добавлю:
3) новая задача и/или предметная область, в которой надо еще с типовыми алгоритмами разобраться, понять нюансы и т.п.
Я так проги по перколяции писал. Сначала пишу, чего и в каком порядке надо делать на русском, а потом перевожу в код.
Или вот буду писать систему психологического тестирования программистов — тоже без осознания чего и как кода не напишешь.
4) При необходимости писать на новом языке — сначала на русском, потом подбираешь подходящие конструкции нового языка (ну, конечно, это не касается совсем уж тривиальных, которые есть в любом языке)
Хочешь быть счастливым — будь им!
Без булдырабыз!!!
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам.
Иногда да, иногда — нет.
G> И комментарии не только не нужны, а вообще вредны.
Лишние комментарии не нужны, нелишние — нужны. Универсального рецепта нет.
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
1) Те кто против любых комментов. Берешь какой нибудь нетривиальный кусок кода (нетривиальный в плане логики или завязанный на какую то неочевидную тонкость), удаляешь все комменты. Потом просишь протестантов быстро посмотреть кусок кода и объяснить как он работает.
2) Те кто любит лишние комменты. Берешь кусок кода с комментами в стиле "Капитан Очевидность" и настоятельно просишь пояснить, в какой момент данный коммент упростит жизнь читающему код.
Здравствуйте, Denwer, Вы писали:
D>А писать понятный код не получается? Ну комментарии можешь для себя писать, но понятный код это обязательное условие по сути. А то бывает смотришь код, а там перменные а1, а2, а3 и к ним комментарии. А нельзя их обозвать более понятно и не пистаь комментарий?
Иногда бывает, что нельзя. Реализуешь какую-нибудь математику по стандартному описанию алгоритма, а там x, y, S. И что делать?
Здравствуйте, Hobbes, Вы писали:
H>Иногда бывает, что нельзя. Реализуешь какую-нибудь математику по стандартному описанию алгоритма, а там x, y, S. И что делать?
Ну, у математиков свой подход к именованию переменных и вообще к программированию.
Математики в злобной числодробительной программе делали такую шапку, в которую записывали, откуда взяты алгоритмы (монография, авторы, год издания; статья, название,журнал, №, год, авторы; диссертация, автор). И оставляли имена максимально близкими к тем, что в формулах. Выглядел код (на Фортране) для постороннего полным бредом. Но один математик свободно читал такой код, написанный другим математиком.
Здравствуйте, Privalov, Вы писали:
P>Математики в злобной числодробительной программе делали такую шапку, в которую записывали, откуда взяты алгоритмы (монография, авторы, год издания; статья, название,журнал, №, год, авторы; диссертация, автор). И оставляли имена максимально близкими к тем, что в формулах. Выглядел код (на Фортране) для постороннего полным бредом. Но один математик свободно читал такой код, написанный другим математиком.
Вот-вот, я про это и говорю.
И это необязательно математики и математика. Любая нетривиальная логика из предметной области упирается в то, что в коде надо откомментировать как минимум, откуда это взялось (прямо ссылкой на документацию), и что происходит на данном конкретном этапе.
Здравствуйте, Hobbes, Вы писали:
H>И это необязательно математики и математика. Любая нетривиальная логика из предметной области упирается в то, что в коде надо откомментировать как минимум, откуда это взялось (прямо ссылкой на документацию), и что происходит на данном конкретном этапе.
математику я взял исключительно в качестве примера. Просто потому, что у меня был некоторый опыт в числодробительной области. Работал с матерыми математиками. А комментарии в фортрановском коде оставлял больше для себя, чем для них. Я к проекту кое-где сишные модули подключил, оставлял заметки. До того случая у меня не было опыта сборки модулей, сделанных на разных языках.
Сегодня я обычно вставляю комментарии, если использую какую-либо конструкцию или структуру впервые. Или ставлю напоминалку на будущее: там изменить, а тут проверить. А вместо устаревшего объекта использовать новый (и такое бывает). Иногда неясно бывает, как написать метод. Тогда делаю его пустым и сначала пишу в нем, что нужно сделать. И постепенно заменяю комментарии кодом.
Иногда слишком подробные комментарии бывают вредными (для комментирующего). Но это уже другая история.
Здравствуйте, CreatorCray, Вы писали:
S>>По git blame сразу видно, какой коммит изменил больше всего CC>И как git blame заставить показать коммит 5летней давности, почти все строки которого были за это время потроганы сотней других коммитов? CC>У p4 был отличный тул timelapse, который позволял ходить по истории туда-сюда в наглядном виде и видеть что происходило в конкретном range строк. CC>Git так не умеет. Можно только врукопашку.
В Идее есть пункт контекстного меню Git/Show history for selection на выделенном фрагменте. Это не оно?
Здравствуйте, gyraboo, Вы писали:
G>В Идее есть пункт контекстного меню Git/Show history for selection на выделенном фрагменте. Это не оно?
У меня идеи нету, так что проверить не могу. Может таки и сделали наконец.
Надо бы пнуть Atlassian чтоб они в своём SourceTree сделали, вот только у них проблемы покруче пока — у них походу квадратичная сложность где то затесалась и на сколь либо больших репах оно тормозит просто ацки.
Здравствуйте, CreatorCray, Вы писали:
CC>Надо бы пнуть Atlassian чтоб они в своём SourceTree сделали, вот только у них проблемы покруче пока — у них походу квадратичная сложность где то затесалась и на сколь либо больших репах оно тормозит просто ацки.
Проще идею поставить Атлассиан не раскачаешь, больше 5 лет не могут сделать архивирование репозиториев в битбакете
В Идее есть локальная история тоже, иногда спасает и экономит часы работы
Здравствуйте, CreatorCray, Вы писали:
G>>В Идее есть пункт контекстного меню Git/Show history for selection на выделенном фрагменте. Это не оно? CC>У меня идеи нету, так что проверить не могу. Может таки и сделали наконец.
В Идее это сделали уже как много лет. Как и множество других ништяков, о которых в других IDE только грезят или даже не знают что такое вообще есть, хотя эти ништяки нехило бустят скорость и удобство разработки. Идея стала легендой не просто так.
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились.
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Напоминает табы против пробелов. Хочу отдельно отметить только один аспект комментариев — чисто визуальный, графический. Комментарии хорошо заметны в коде, и я их расставляю по своей системе в каких-то структурных местах, даже если там нет особой логики, комментировать, собственно, нечего. Разделяю/выделяю смысловые или структурные группы, блоки. Использую символы подчеркивания, звездочки — такое. Без попугайства, не разрисовываю, у меня выработалась простая система.
В результате, когда бегаешь по коду, глаз сам цепляется за нужные места, не надо использовать высшие функции мозга для навигации. Я, например, когда скроллю код, мгновенно расфокусирую и фокусирую зрение. Может быть, это позволило мне не убить зрение окончательно за 100 лет за компом. Каменты при скроллинге и расфокусировке глаз помогают останавливаться, где надо.
Естественно, таких каментов должн быть немного — один на 10-200 строчек.
А теперь о главном, моей прогрессивной новаторской идее. Исходя из общей логики развития цивилизации, выражющейся в миграции документации и вообще всего в ютуб и тик-ток, предлагаю предложить внедрить в IDE комментирование кода в формате видео. Видео, конечно же, сохранять в облаке.
Здравствуйте, goto, Вы писали:
G>А теперь о главном, моей прогрессивной новаторской идее. Исходя из общей логики развития цивилизации, выражющейся в миграции документации и вообще всего в ютуб и тик-ток, предлагаю предложить внедрить в IDE комментирование кода в формате видео. Видео, конечно же, сохранять в облаке.
Крутая идея кстати, давайте ее еще более расширим:
— лайки/дизлайки строкам/кускам кода/функциям/классам;
— подписаться на изменения какого-либо куска кода;
— возможность оставлять комменты кускам кода.
Здравствуйте, gress, Вы писали:
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
У кода должна быть документация. Там надо описать как это собрать, что требуется установить, какая часть программы что делает.
Как отлаживать, что означают логи. Как настроить рабочее окружение с нуля новому человеку. И куча других неочевидных вещей
А в коде непонятно зачем нужны комментарии. Если комментируешь, значит код недостаточно выразителен. Лучше улучшить код, чем тратить время на комментарий.
А ещё комментарии не компилируются. И когда код изменится — они останутся, станет ещё хуже, т.к. вряд ли кто-то когда-то удалит этот комментарий. В любом случае на него будет тратится время.
Есть функция getUserName, и к ней написан комментарий "поменять имя текущего пользователя на новое случайно сгенерированное и вернуть предыдущее значение". Надо ли пояснять, что код плохой и комментарий не улучшает ситуацию?
Плохой код с комментариями лучше, чем просто плохой код. Но не на много. Лучше всё же тратить время на улучшения самого кода. А комментарии — это запашок, который подскажет, что здесь надо убрать.
Здравствуйте, blacktea, Вы писали:
B>Крутая идея кстати, давайте ее еще более расширим:
Да, очень крутая. Я убежден, что со временем ее воплотят.
B>- лайки/дизлайки строкам/кускам кода/функциям/классам; B>- подписаться на изменения какого-либо куска кода; B>- возможность оставлять комменты кускам кода.
Как ни парадоксально, но развитие идеи уже новаторским не является. Давно есть форумы, репозитории, где куски кода и комментарии лайкают и делают с ними все.
Здравствуйте, Hobbes, Вы писали:
H>Иногда бывает, что нельзя. Реализуешь какую-нибудь математику по стандартному описанию алгоритма, а там x, y, S. И что делать?
Обычно просто дают ссылку на книгу или статьи, где это всё подробно описано.
Здравствуйте, alzt, Вы писали:
A>Здравствуйте, bnk, Вы писали:
bnk>>Вещи, которые не очевидны, комментировать все еще нужно.
A>В большинстве случаев можно упростить код и сделать так, что всё станет очевидно.
Особенно очевидно смотреть на какой-нибудь интерпрайз java код, где всё на фабриках и стратегиях. А вот код который хоть что-то полезное делает надо очень поискать.
Здравствуйте, kov_serg, Вы писали:
A>>В большинстве случаев можно упростить код и сделать так, что всё станет очевидно. _>Особенно очевидно смотреть на какой-нибудь интерпрайз java код, где всё на фабриках и стратегиях. А вот код который хоть что-то полезное делает надо очень поискать.
Если фабрика добавлена ради фабрики студентом, который прочёл о паттернах, то скорее всего у кода есть куча недостатков. И фабрика там только мешает, т.к. вставлена не там, где действительно нужна. А в остальных случаях этот код проще менять и поддерживать.
Ну и в целом когда работаешь с плохим кодом, и думаешь как добавить новую функциональность так, чтобы не ухудшить его ещё. То почти всегда первым шагом будет рефакторинг: выделить интерфейсы, методы, разбить перегруженные классы, добавить фабрики и декораторы. А потом уже новая функциональность добавляется проще и гибче.
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились.
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Вообще, дело тут в том, что руководство всегда пытается как-то формализовать правила написания чистого, качественного, поддерживаемого кода, но задача эта нерешаема. Руководителям, да и многим рядовым разработчикам хочется иметь какие-то понятные и измеримые критерии, и часто это превращается в религию. Комментарии в коде отличный пример таких религиозных установок.
Когда-то давным давно, умные люди догадались, что в код можно вставить комментарии, в которых можно оъбъяснить для последующих поколений разработчиков, что, зачем и почему. Очевидно, что можно разъяснить все более подробно (написать побольше комментариев) и тогда код станет понятнее. Эта идея была взята на вооружение руководителями, которые стали требовать от подчиненных писать комментарии, и чем больше комментариев, тем лучше. Даже сделали всякие автоматические тулзы, чтобы подсчитать количество комментариев и настучать по голове, тому, у кого комментов мало. Что будет делать рядовой разработчик, от которого требуют написать комментарии к каждой строчке? У разработчика нет времени, его главная задача не завалить дедлайны, и ему по большей части наплевать, на тех, кто потом будет разбираться в его коде, ему просто хочется побыстрее отделаться и начать заниматься чем-то новым. Естественно он не будет долго руздумывать о том, как бы получше разъяснить неочевидные моменты, а тупо нафигачит везде очевидных и бесполезных комментов типа:
a + b // add a to b
getContext() // get context
Так шли годы, и были написаны террабайты кода с кучей бесполезных никому не нужных комментов. Потом кто-то умный высказал опять же очевидную и совершенно верную вещь: Комментарии ради комментариев не нужны, зачем комментировать очевидные вещи? А если в коде что-то неочевидное, то, может прежде чем писать комментарий, стоит подумать: не переписать ли этот кусок кода так, чтобы он и без комментариев стал понятным?
Эта идея была встречена с большим энтузиазмом, как разработчиками, которым неохота было писать комменты к каждой строчке, так и руководителями, которые надеялись, что так можно сэкономить время. И естественно это было превращено в религию! И было введено требование писать только самодокументирующийся код и не писать комментарии. Теперь, если в коде вдруг на код ревью видят комментарий, то разработчику говорят, что тут у него код написан неочевидно, и пусть он перепишет его так, чтобы комментарий был не нужен. Разработчику естественно переписывать неохота, поэтому после пары таких случаев он перестал писать комменты вообще даже там где они реально нужны, чтобы не придирались лишний раз.
То же самое касается всех остальных правил написания чистого кода, длинное имя переменной типа objectContextHandle часто несет не больше смысла чем однобуквенное. Одна длинная функция, может читаться проще чем множество мелких (не надо прыгать по коду и смотреть что делает каждая из функций). Главное не превращать эти правила в религию.
Здравствуйте, alzt, Вы писали:
A>У кода должна быть документация. Там надо описать как это собрать, что требуется установить, какая часть программы что делает. A>Как отлаживать, что означают логи. Как настроить рабочее окружение с нуля новому человеку. И куча других неочевидных вещей
Документация это те же комментарии, только вынесенные в отдельный файл. Документация тоже не компилируется и устаревает, и там точно так же может быть написана устаревшая и бесполезная информация (очень часто так оно и есть). Точно так же можно написать кучу бесполезной документации, которая будет объяснять очевидные вещи и умалчивать о том, что действительно важно.
Никакой разницы нет.
A>А в коде непонятно зачем нужны комментарии. Если комментируешь, значит код недостаточно выразителен. Лучше улучшить код, чем тратить время на комментарий.
Проблема в том, что не всегда так просто написать код который будет прост и понятен. Бывает так, что имя переменной или функции получается слишком уж длинным, что его совершенно невозможно использовать, а если имя сократить, то оно уже не совсем точно отражает, то, что делает эта функция. Бывает, что в коде для совместимости с чем-то старым надо сделать какую-то на первый взгляд совершенно ненужную вещь. Бывает, что тебе просто хочется поъянить, почему ты делаешь именно так, а не подругому, хотя на первый взгляд кажется, что должно быть не так, но это только на первый взгляд. Бывает, что где-то код приходится оптимизировать, и он получается быстрый но совершенно неочевидный.
A>А ещё комментарии не компилируются. И когда код изменится — они останутся, станет ещё хуже, т.к. вряд ли кто-то когда-то удалит этот комментарий. В любом случае на него будет тратится время.
Да, это проблема. С этим надо бороться, но точно так же фунцция может начать делать что-то новое, и ее имя перестанет отражать то, что она делает. Комментарии точно так же как и документацию надо поддерживать в актуальном состоянии. Их не должно быть много, и там надо писать именно важные вещи, а не все подряд.
A>Есть функция getUserName, и к ней написан комментарий "поменять имя текущего пользователя на новое случайно сгенерированное и вернуть предыдущее значение". Надо ли пояснять, что код плохой и комментарий не улучшает ситуацию?
Это еще не самый плохой вариант, тут сразу ясно, что либо у функции название плохое, либо коммент устарел, и надо что-то поменять.
ИМХО хуже когда так:
getUserName(); // get user name
Вот тут коммент совершенно бесполезен и не говорит вообще ни о чем. Вообще в комментарии к фунции getUserName, хорошо было бы описать возможные граничные условия и ошибки, например, что вернет функция если юзера как бы нет (он не залогинен), будет ли это null, или какое-нибудь дефолтное имя, или вообще будет exception?
A>Плохой код с комментариями лучше, чем просто плохой код. Но не на много. Лучше всё же тратить время на улучшения самого кода. А комментарии — это запашок, который подскажет, что здесь надо убрать.
Главное не давать тебе с таким подходом быть руководителем. Когда ты будешь видеть коммент, будешь сразу на них наезжать и требовать что-то переписать и убрать. В итоге они вместо улучшения кода, просто перестанут писать комменты, и вместо плохого кода с комментариями станут выдавать просто плохой код.
V>/*********************************************************
V>* File: Foo.java
V>* Purpose: Foo class implementation
V>* Notice: (c) 1066 Foo industries. All rights reserved.
V>********************************************************/
Кстати, ИМХО отличный пример бесполезной документации. Что полезного тут написано?
Что файл называется Foo.java, можно понять просто по названию файла.
Что он содержит реализацию класса Foo, ну, это и так можно понять открыв файл, и увидев, что там ничего нет кроме этого класса.
Сopyright, наверное для юристов есть какой-то смысл (хотя, для меня загадка, какой именно, если код не распространяется публично), но для разработчиков вещь бесполезная.
Javadoc вполне может сгенерировать документацию и без этого заголовка.
Польза от такой документации будет только в том случае, если там реально писать что-то полезное, но обычно народ забивает на это дело и ограничивается тупыми фразами типа "Foo class implementation" в итоге код как бы докумментирован, но смысла в этой доке никакого... фактически документации нет.
Я вообще за то, чтоб докумментировать код с помощью doxygen или javadoc, но там должно быть написано что-то важное, если это писать не охота, то лучше уж ничего не писать.
Здравствуйте, ksandro, Вы писали:
K>Документация это те же комментарии, только вынесенные в отдельный файл. Документация тоже не компилируется и устаревает, и там точно так же может быть написана устаревшая и бесполезная информация (очень часто так оно и есть). Точно так же можно написать кучу бесполезной документации, которая будет объяснять очевидные вещи и умалчивать о том, что действительно важно. K>Никакой разницы нет.
Документация компакта, и описывает высокоуровневые вещи, и то, чего просто нет в коде (например, как часто у нас релизы и почему используется именно этот стек технологий). Документацию проще писать, когда в команде появляется новый человек, либо старые переходят на другие части. То, что им не понятно — стоит добавить.
K>Проблема в том, что не всегда так просто написать код который будет прост и понятен. Бывает так, что имя переменной или функции получается слишком уж длинным, что его совершенно невозможно использовать, а если имя сократить, то оно уже не совсем точно отражает, то, что делает эта функция. Бывает, что в коде для совместимости с чем-то старым надо сделать какую-то на первый взгляд совершенно ненужную вещь.
Написать хороший код не просто, я не спорю. Добавить комментарий — это не самое плохое, но почти всегда в таких случаях можно было написать код лучше.
K>Бывает, что тебе просто хочется поъянить, почему ты делаешь именно так, а не подругому, хотя на первый взгляд кажется, что должно быть не так, но это только на первый взгляд. Бывает, что где-то код приходится оптимизировать, и он получается быстрый но совершенно неочевидный.
Если это какая-то особенность предметной области, то да. Надо добавлять подробный комментарий. Из кода это знание не получишь.
Во всех остальных случаях лучше выразить в самом коде.
K>Да, это проблема. С этим надо бороться, но точно так же фунцция может начать делать что-то новое, и ее имя перестанет отражать то, что она делает. Комментарии точно так же как и документацию надо поддерживать в актуальном состоянии. Их не должно быть много, и там надо писать именно важные вещи, а не все подряд.
Рефакторинг надо проводить постоянно. Если ты меняешь поведение функции, то надо менять и её название.
Проблемы могут только с интерфейсами возникнуть, которые связывают разные компоненты.
K>Главное не давать тебе с таким подходом быть руководителем.
Руководитель в код не смотрит.
K>Когда ты будешь видеть коммент, будешь сразу на них наезжать и требовать что-то переписать и убрать.
Комментарий показывает, что есть проблема. Его удаление проблему не решает. Но да, может сделать проблему менее заметной.
K>В итоге они вместо улучшения кода, просто перестанут писать комменты, и вместо плохого кода с комментариями станут выдавать просто плохой код.
Код ревью должно решать такие проблемы.
Нормальный подход — это не влепить коммит, который пропустят любой ценой. А написать хороший код, который будет легко поддерживать, и в котором будет поменьше багов. Если есть комментарий, то это подсказка для написавшего код — зачем он его добавил. Что он может сделать, чтобы код стал лучше без комментария.
Но без желания писать хороший код всё это бесполезно. Один ты не сможешь всех заставить писать нормално.
В среднем программисты готовы писать хороший код, если их никто не подгоняет.
Здравствуйте, ksandro, Вы писали:
K>То же самое касается всех остальных правил написания чистого кода, длинное имя переменной типа objectContextHandle часто несет не больше смысла чем однобуквенное. Одна длинная функция, может читаться проще чем множество мелких (не надо прыгать по коду и смотреть что делает каждая из функций). Главное не превращать эти правила в религию.
Ну вот нет. Много раз были длинные функции, которые вроде бы хорошо читались. Но как только разбивал их на мелкие, так всегда оказывалось, что становилось лучше.
Если вдруг длинные функции читать проще, то можно делать такой обратный рефакторинг — объединять несколько функций в одну, чтобы она стала больше. Только ни разу о таком не слышал. Подозреваю из-за того, что во-первых надо приложить усилия, а во-вторых станет хуже.
Комментируются:
1) сигнатуры методов для доксигена и проч систем автоматическойгенерации справки;
2) выборочные места в коде, которые нетривиальны с т.з. логики.
Степень "нетривиальности" определяется либо автором кода, либо максимум ревьюерами коммита.
и поддерживать код — легко и просто .. (особенно на Java)
