для меня оно очень затрудняет анализ программы,
особенно когда имеются 3 версии исходника, созданных из одной любителями
технологии Copy-n-paste и оказывается что отличаются они в основном наличием
комментариев в разных местах (вот бы научить WinDiff игнорировать комментарии
при сравнении)
про рефакторинг тоже уже говорили — когда переносишь метод в другое место,
ранее написанные комментарии теряют смысл
Здравствуйте, Awaken, Вы писали:
A>для меня оно очень затрудняет анализ программы, A>особенно когда имеются 3 версии исходника, созданных из одной любителями A>технологии Copy-n-paste и оказывается что отличаются они в основном наличием A>комментариев в разных местах (вот бы научить WinDiff игнорировать комментарии A>при сравнении) A>про рефакторинг тоже уже говорили — когда переносишь метод в другое место, A>ранее написанные комментарии теряют смысл
Мне очень понравилась мысль в одной книжке по рефакторингу. Выглядела она примерно так
Если код требует комментариев, то его надо рефакторить
Может надо изобрести параметризованные комментарии?
// класс @CurrentClass предназначен для того-то и того-то.
// метод @CurrentMethod нужен для того-то, в параметре @FindParam(@CurrentMethod, int, 0) хранится то-то...
и т.д.? И чтоб IDE и diff подставляли туда нужные параметры
Тезис в виде сабжа придумали лентяи, бездельники и лодыри. Много коментариев не только вредно, но и полезно. Другое дело, если в них вместо разумного, светлого и вечного сплошной бред.
Если нам не помогут, то мы тоже никого не пощадим.
Здравствуйте, IT, Вы писали:
IT>Здравствуйте, Awaken, Вы писали:
IT>Тезис в виде сабжа придумали лентяи, бездельники и лодыри. Много коментариев не только вредно, но и полезно. Другое дело, если в них вместо разумного, светлого и вечного сплошной бред.
А я согласен с сабжем.
Коментарии в хидерах (конечно имею ввиду С++) колько затрудняют их использование. Коментарий признаю только в качестве пролога файла. Особенно бесят заголовочные файлы в которых написана куча ненужной фигни для генерации doxygen-ом или подобными инструментами. Пользоваться ими невозможно.
Плохой код коментарии лучше не сделают. Хороший — сам себя коментирует.
А вот что полезно по настоящему — это сопроводительная документация, с описанием логики и структуры программы. Но она должна быть отдельно.
EF>>Плохой код коментарии лучше не сделают. Хороший — сам себя коментирует.
IT>Вот вот. Именно это и есть главный тезис лентяев При грамотно написанных коментариях код можно читать как книгу.
это когда они написаны там где надо. например я приветствую комментарии к параметрам особо
замудренных и редко используемых функций Win32 API
а вот такие "потрясные" комментарии только засоряют код и никакой информативности
не добавляют
Customer.Save // save the customer object
или еще хуже
try// enter the try block
{
...
catch(...) // exception handling
Здравствуйте, Ведмедь, Вы писали:
В>Мне очень понравилась мысль в одной книжке по рефакторингу. Выглядела она примерно так В>Если код требует комментариев, то его надо рефакторить
Согласен.
... << RSDN@Home 1.0 beta 4 >>
Пусть это будет просто:
просто, как только можно,
но не проще.
(C) А. Эйнштейн
Здравствуйте, EugenF, Вы писали:
EF>Коментарии в хидерах (конечно имею ввиду С++) колько затрудняют их использование. Коментарий признаю только в качестве пролога файла. Особенно бесят заголовочные файлы в которых написана куча ненужной фигни для генерации doxygen-ом или подобными инструментами. Пользоваться ими невозможно.
1. Надо писать коомменты, которыми удобно пользоваться
2. Где ж ещё, кроме как не в хедерах, писать описание класса, членов, методов etc.? Писать в определении? Замучаешьсяскакать по многокилобайтному тексту
EF>А вот что полезно по настоящему — это сопроводительная документация, с описанием логики и структуры программы. Но она должна быть отдельно.
Документация необходима, НО
Понадобилось мне найти, что означает какой-то метод класса и его параметры... лезть в документ, искать описание? мне проще перейти к заголовочному файлу и за пару секунд найти требуемое.
A>Документация необходима, НО A>Понадобилось мне найти, что означает какой-то метод класса и его параметры... лезть в документ, искать >описание? мне проще перейти к заголовочному файлу и за пару секунд найти требуемое.
для этого нужна специальная среда разработки поддерживающая хранилище доков в html
в программе в комментарии пишется ссылка, ты кликаешь на нее и попадаешь в соответствующий
раздел документации (который не засоряетп программу а хранится в отдельном месте)
A>А про doxygen ты зря, хорошая тулза...
Здравствуйте, Awaken, Вы писали:
EF>>>Плохой код коментарии лучше не сделают. Хороший — сам себя коментирует.
IT>>Вот вот. Именно это и есть главный тезис лентяев При грамотно написанных коментариях код можно читать как книгу.
A>это когда они написаны там где надо. например я приветствую комментарии к параметрам особо A>замудренных и редко используемых функций Win32 API A>а вот такие "потрясные" комментарии только засоряют код и никакой информативности A>не добавляют
A>
A>Customer.Save // save the customer object
A>
A>или еще хуже
A>
A>try// enter the try block
A>{
A>...
A>catch(...) // exception handling
A>
A>
Остаётся только догадываться о мотивах, заставивших программиста написать ЭТО, но наличие таких комментариев не повод их ругать. Можно привести пример плохо написаного кода на С++ и что, это повод ругать язык? Программу даже средней сложности без комментариев понять гораздо сложнее. Например очень полезны комментарии типа "почему сделано так а не иначе", на случай, если кто-то задумает оптимизировать код. А невозможность отключить комментарии в WinDiff, это недостаток WinDiff, а не вредность комментариев.
II>Остаётся только догадываться о мотивах, заставивших программиста написать ЭТО, но наличие таких
видимо он только xnj открыл для себя конструкцию try...catch
>комментариев не повод их ругать. Можно привести пример плохо написаного кода на С++ и что, это повод ругать
когда программист придумывает осмысленные идентификаторы то надобность в подобных
комментариях отпадает, тем более в ОО-языках как C++ или Java:
customer.addOrder(orderData); // что здесь непонятно?
Здравствуйте, Awaken, Вы писали:
A>когда программист придумывает осмысленные идентификаторы то надобность в подобных A>комментариях отпадает, тем более в ОО-языках как C++ или Java: A>
A>customer.addOrder(orderData); // что здесь непонятно?
A>
Естественно отпадает. И так понятно что такое customer и что с ним делает addOrder. Понятно, что перегружать программу комментариями не стоит, но существуют случаи, когда без них не обойтись. Например каое-либо не тривиальное решение, или что-то типа "Сделано так из-за ошибки в MFC". Может быть вопрос не в том, нужны комментарии или нет, а в том, стоит ли комментировать всё что ни попадя?
Здравствуйте, Awaken, Вы писали:
A>когда программист придумывает осмысленные идентификаторы то надобность в подобных A>комментариях отпадает, тем более в ОО-языках как C++ или Java: A>
A>customer.addOrder(orderData); // что здесь непонятно?
A>
Непонятно зачем это надо. Не всегда из вида конструкции очевидно ее назначение.
Здравствуйте, Areex, Вы писали:
A>Здравствуйте, Awaken, Вы писали:
A>>когда программист придумывает осмысленные идентификаторы то надобность в подобных A>>комментариях отпадает, тем более в ОО-языках как C++ или Java: A>>
A>>customer.addOrder(orderData); // что здесь непонятно?
A>>
A>Непонятно зачем это надо. Не всегда из вида конструкции очевидно ее назначение.
Зачем это надо ? Конечно, если программу читает человек, который не хнает даже постановки задачи
то ему нужно это объяснить. Но обычно в чужих программах разбираются люди, занимающиеся сопровождерием,
а они знают что и зачем надо.
Излишняя эмоциональность моих ответов объясняется тем, что мне приходится иногда сопровождать программу
одного вот такого любителя комментариев. Так вот — если код уродский, комментарии его не спасают. В хорошем
коде нужно комментировать только места в которых используются нестандартные решения, иначе код становится нечитаемым именно из-за комментариев.
И ещё ращз напишу. Для меня намного важнее сопроводительная документация с описанием структуры программы и каких-то алгоритмов, но, к сожалению, её мало кто пишет.
Здравствуйте, Aquary, Вы писали:
A>Здравствуйте, EugenF, Вы писали:
A>2. Где ж ещё, кроме как не в хедерах, писать описание класса, членов, методов etc.? Писать в определении?
A>Понадобилось мне найти, что означает какой-то метод класса и его параметры... лезть в документ, искать описание? мне проще перейти к заголовочному файлу и за пару секунд найти требуемое.
Именно, но комментарии в хидере делают его намного больше. Хидером в котором минимум текста, легче пользоваться. Обычно я знаю что делает та или иная функция. Мне просто нужно уточнить типы и порядок параметров. Для этого не нужны комментарии.
A>А про doxygen ты зря, хорошая тулза...
Здравствуйте, EugenF, Вы писали:
EF>Зачем это надо ? Конечно, если программу читает человек, который не хнает даже постановки задачи EF>то ему нужно это объяснить. Но обычно в чужих программах разбираются люди, занимающиеся сопровождерием, EF>а они знают что и зачем надо.
Они могут забыть, вернее они точно забудут через не долгое время.
Не всегда из очевидной конструкции следует очевидное назначение. Почему так, почему не иначе. Да мало ли тонкостей ясных как день сегодня и совершенно хренпоймешь завтра.
EF>Излишняя эмоциональность моих ответов объясняется тем, что мне приходится иногда сопровождать программу EF>одного вот такого любителя комментариев. Так вот — если код уродский, комментарии его не спасают. В хорошем EF>коде нужно комментировать только места в которых используются нестандартные решения, иначе код становится нечитаемым именно из-за комментариев.
Если ты столкнулся с кривым кодом + кривые комментарии, это не значит, что виноваты в этом комментарии.
А излишняя эмоциональность верный признак, что с аргументами слабо, так что лучше нажал бы на них.
EF>И ещё ращз напишу. Для меня намного важнее сопроводительная документация с описанием структуры программы и каких-то алгоритмов, но, к сожалению, её мало кто пишет.
На моем личном опыте важно и то, и то. Просто все надо делать хорошо, а не отмазки искать почему тебе лень писать доки да комментарии. Да и как они тебе могут помешать? Ну не нравится игнорируй их.
Кр-ть — с.т.
Если нам не помогут, то мы тоже никого не пощадим.
