Здравствуйте, MTD, Вы писали:
MTD>Это единственный случай когда в хорошем коде комментарий уместен.
"Хороший код" иллюстрирует максимум только то, что он делает. Он не может описать того, что он не делает, и почему он этого — ещё или уже — не делает.
Всегда есть множество вариантов сделать одно и то же. И простое предъявление одного из вариантов не говорит о том, почему именно ему отдано предпочтение перед другими. Планируется какой-то рефакторинг, учтены какие-то ограничения одного из компиляторов, воркэраунд вокруг недокументированного поведения сторннего API, etc, etc, etc. "В хорошем коде комментариев быть не должно" — это весьма популярный, яркий, лаконичный, ёмкий и совершенно неправильный принцип. Используется в основном теоретиками и прочими гуманитариями.
Здравствуйте, Qbit86, Вы писали:
Q>"Хороший код" иллюстрирует максимум только то, что он делает. Он не может описать того, что он не делает, и почему он этого — ещё или уже — не делает.
Действительно, почему функция OpenFile не форматирует диск? Непорядок, надо фичу добавить, но аккуратно задокументировать!
Q>Используется в основном теоретиками и прочими гуманитариями.
А обвинения в увлечении теорией, по моему опыту, звучат в основном от любителей трясти, а не думать.
Здравствуйте, Хон Гиль Дон, Вы писали:
ХГД>Есть куча ситуаций, где недостаточно внимательный разработчик может нарваться на неприятности. Я, например, всегда комментирую "проваливающиеся" (без break) ветки в switch, или места, где важен порядок объявления членов класса.
Перепиши код проще, чтобы недостаточно внимательный разработчик не нарвался — гарантии, что он прочтет твой комментарий нет.
ХГД>Со сторонними библиотеками тоже всяких приколов хватает. Вообще, нарвался на неожиданность — прокомментируй.
Здравствуйте, MTD, Вы писали:
Q>>"Хороший код" иллюстрирует максимум только то, что он делает. Он не может описать того, что он не делает, и почему он этого — ещё или уже — не делает. MTD>Действительно, почему функция OpenFile не форматирует диск? Непорядок, надо фичу добавить, но аккуратно задокументировать!
OpenFile? Что ещё за OpenFile? Почему в этом месте разраюотчик решил открыть какой-то файл? Этот код может же выполняться на мобильной платформе, где нельзя просто так взять, и открыть файл. Или не будет выполняться? Зачем открывать какие-то файлы, если в любом языке и библиотеке есть примитивы для работы с XML или другими форматами данных? Я программировал на C++ и C# под десктоп, iOS и Android. И везде OpenFile почти наверняка вызвал бы вопросы.
MTD>А обвинения в увлечении теорией, по моему опыту, звучат в основном от любителей трясти, а не думать.
Если человек не может вообразить примеры, когда полезны комментарии в коде — значит, он чужой код не читает. Может, он джедай-одиночка; свой-то код, понятно, "всегд хороший и не нуждается в комментариях".
Здравствуйте, Хон Гиль Дон, Вы писали:
ХГД> Я, например, всегда комментирую "проваливающиеся" (без break) ветки в switch, или места, где важен порядок объявления членов класса.
Ага, классный принцип — закладывать мины и обставлять их флажками
Здравствуйте, MTD, Вы писали:
Z>>например мы реализовали какой-то сложный математический Z>>метод, нужен хотя бы комментарий, типа метод такой-то, см. статью такую-то,
MTD>Это единственный случай когда в хорошем коде комментарий уместен.
Не совсем. IMHO, при развитии/поддержке очень полезны комментарии, отвечающе не на вопрос "что делает код",
а на вопрос "почему/зачем это делается" или "почему это делается именно так, а не иначе".
Здравствуйте, GhostCoders, Вы писали:
GC>Данный код был написан моим сотрудником. Мне этот код не нравится, но он мне отвечает что я субъективен и его код неплох.
лютый трындец. write-only. надо переделать чтоб был единый code design style — префиксы переменных, какие отступы у скопов и так далее, комментарии должны быть комментариями, а не отладочным выводом и функции типа equal_values не должны иметь параметров, которые не используются никогда.
Функция которая открывает файл.
Q>Почему в этом месте разраюотчик решил открыть какой-то файл?
Действительно, зачем в методе ReadConfigFromFile (ПрочестьКонфигурациюИзФайла) разработчику нужно открыть файл? Непонятно! Надо чтобы диск форматировался и само-собой оставить об этом комментарий.
Q>Этот код может же выполняться на мобильной платформе
Придумай что-нибудь оригинальней, передергивания стали скучными.
Q>Если человек не может вообразить примеры, когда полезны комментарии в коде — значит, он чужой код не читает. Может, он джедай-одиночка; свой-то код, понятно, "всегд хороший и не нуждается в комментариях".
Я читал очень много кода, был код который читался замечательно без комментариев, было много говнокода "отлично" прокомментированного:
file f = open("xxx") // Открываем файл
x = read(f, 5) // Читаем из файла 5 байт
А еще, попадался код с историей в десяток лет, где изначально осмысленные комментарии устаревали и порой вообще вводили в заблуждение.
Здравствуйте, MTD, Вы писали:
Q>>"Хороший код" иллюстрирует максимум только то, что он делает. Он не может описать того, что он не делает, и почему он этого — ещё или уже — не делает.
MTD>Действительно, почему функция OpenFile не форматирует диск? Непорядок, надо фичу добавить, но аккуратно задокументировать!
OpenFile — очень хороший пример функции, документирование которой строго обязательно. Описание, какие режимы можно использовать, на каких платформах (если поддерживает больше одной) и файловых системах и как они будут работать, а также прямое описание ошибочных ситуаций.
Более того, во многих случаях необходимо документировать также и использование оной функции. Чтобы указать, почему используется именно этот режим открытия, или почему тут совершенно необходимо использование юникодной версии и префикса "\\?\" и т.д.
Здравствуйте, landerhigh, Вы писали:
L>OpenFile — очень хороший пример функции, документирование которой строго обязательно. Описание, какие режимы можно использовать, на каких платформах (если поддерживает больше одной) и файловых системах и как они будут работать, а также прямое описание ошибочных ситуаций.
L>Более того, во многих случаях необходимо документировать также и использование оной функции. Чтобы указать, почему используется именно этот режим открытия, или почему тут совершенно необходимо использование юникодной версии и префикса "\\?\" и т.д.
это какая-то утопия, имхо =)
пачка бумаги А4 стОит 2000 р, в ней 500 листов. получается, лист обычной бумаги стОит дороже имперского рубля =)
Здравствуйте, niXman, Вы писали:
L>>Более того, во многих случаях необходимо документировать также и использование оной функции. Чтобы указать, почему используется именно этот режим открытия, или почему тут совершенно необходимо использование юникодной версии и префикса "\\?\" и т.д.
X>это какая-то утопия, имхо =)
Отнюдь. Харрасмент, буллинг и геноцид, ковровые бомбардировки и обыкновенный фашизм во время код ревью творят живительные чудеса. Через полгода подопытные (если не уволились раньше) даже перестают воспринимать критику кода как личное оскорбление.
Здравствуйте, landerhigh, Вы писали:
L>Отнюдь. Харрасмент, буллинг и геноцид, ковровые бомбардировки и обыкновенный фашизм во время код ревью творят живительные чудеса. Через полгода подопытные (если не уволились раньше) даже перестают воспринимать критику кода как личное оскорбление.
я согласен с тем, что такой код хорошо и приятно поддерживать. но я сомневаюсь что такое возможно в нашей-то реальности
пачка бумаги А4 стОит 2000 р, в ней 500 листов. получается, лист обычной бумаги стОит дороже имперского рубля =)
Здравствуйте, niXman, Вы писали:
X>я согласен с тем, что такой код хорошо и приятно поддерживать. но я сомневаюсь что такое возможно в нашей-то реальности
К совершенству надо стремиться. Даже если оно недостижимо. Иначе бренность бытия поглотит и само существование станет бессмысленным
Здравствуйте, landerhigh, Вы писали:
L>К совершенству надо стремиться. Даже если оно недостижимо. Иначе бренность бытия поглотит и само существование станет бессмысленным
да. об этом я совсем забыл =)
пачка бумаги А4 стОит 2000 р, в ней 500 листов. получается, лист обычной бумаги стОит дороже имперского рубля =)
Здравствуйте, landerhigh, Вы писали:
L>Отнюдь. Харрасмент, буллинг и геноцид, ковровые бомбардировки и обыкновенный фашизм во время код ревью творят живительные чудеса. Через полгода подопытные (если не уволились раньше) даже перестают воспринимать критику кода как личное оскорбление.
расскажите практические примеры, у меня фантазия закончилась на угрозах семье, но код стал реально чище
Здравствуйте, landerhigh, Вы писали:
L>OpenFile — очень хороший пример функции, документирование которой строго обязательно. Описание, какие режимы можно использовать
Хороший код сам является в значительной мере документацией. Можно обозвать метод open и сказать, что он открывает вообще все, детали смотрите в документации. А можно сделать классы File, TcpSocket, SerialPort с методами Open. Затем, метод Open класса File может две строки — путь к файлу и режим открытия, тут без документации не разобраться. А может принимать enum Mode { ReadOnly, WriteOnly, ... } и объект типа FilePath, который представляет собой путь к файлу.
L>на каких платформах (если поддерживает больше одной)
Сова затрещала. Нормальная библиотека имеет список поддерживаемых платформ — вот ответ. Библиотека которая ведет себя по разному на разных платформах отправляется в топку.
L>и файловых системах и как они будут работать
Ага и на каких дисках, например WD-only, тебе же голову больше занять нечем. Файл — понятие высокоуровневое, забивать себе голову файловыми системами, секторами и блоками как-то неадекватно.
L>а также прямое описание ошибочных ситуаций.
Это да. Только речь то шла о комментариях, документирование отдельная большая тема.
MTD>Хороший код сам является в значительной мере документацией. Можно обозвать метод open и сказать, что он открывает вообще все, детали смотрите в документации. А можно сделать классы File, TcpSocket, SerialPort с методами Open. Затем, метод Open класса File может две строки — путь к файлу и режим открытия, тут без документации не разобраться. А может принимать enum Mode { ReadOnly, WriteOnly, ... } и объект типа FilePath, который представляет собой путь к файлу.
Ага, а как ты узнаешь поведение в случае, если ты хочешь открыть файл для чтения, а он — ридонли? Из документации только, как ты не расписывай API.
L>>на каких платформах (если поддерживает больше одной)
MTD>Сова затрещала. Нормальная библиотека имеет список поддерживаемых платформ — вот ответ. Библиотека которая ведет себя по разному на разных платформах отправляется в топку.
Еще раз — разные платформы имеют право вести себя по-разному. Это обязано быть отражено в документации.
L>>и файловых системах и как они будут работать
MTD>Ага и на каких дисках, например WD-only, тебе же голову больше занять нечем. Файл — понятие высокоуровневое, забивать себе голову файловыми системами, секторами и блоками как-то неадекватно.
Сектора и блоки ты сам сюда притащил. Это называется "довести до абсурда".
А вот про системы, в которых файлов вообще может не быть, тебе уже сказали
Здравствуйте, RonWilson, Вы писали:
RW>расскажите практические примеры, у меня фантазия закончилась на угрозах семье, но код стал реально чище
Фи, как грубо.
Тоньше надо действовать, тоньше. Для разработчика что самое страшное? Что его код могут НЕ ДОПУСТИТЬ К КОММИТУ!!!
Вот отсюда и надо плясать
Здравствуйте, landerhigh, Вы писали:
L>Для разработчика что самое страшное? Что его код могут НЕ ДОПУСТИТЬ К КОММИТУ!!!
ой не факт.
знаю я одного, для которого самое страшное было в том, если его код для обсуждения опубликуют на каких-то форумах
пачка бумаги А4 стОит 2000 р, в ней 500 листов. получается, лист обычной бумаги стОит дороже имперского рубля =)
