Здравствуйте, landerhigh, Вы писали:
L>Ага, а как ты узнаешь поведение в случае, если ты хочешь открыть файл для чтения, а он — ридонли?
Сильно подозреваю, что он откроется нормально и его можно будет прочесть.
L>Из документации только, как ты не расписывай API.
Что значит расписывай API? При чем тут документация, если мы комментарии в коде обсуждали?
L>Еще раз — разные платформы имеют право вести себя по-разному. Это обязано быть отражено в документации.
Нет. Кроссплатформенная библиотека — абстракция над разными платформами, вести себя она должна одинаково иначе не понятно, зачем она нужна, проще нативные библиотеки использовать.
L>Сектора и блоки ты сам сюда притащил. Это называется "довести до абсурда".
Ты с этого начал, я просто сказал, что логично ожидать, что функция с названием OpenFile не будет форматировать диск.
L>А вот про системы, в которых файлов вообще может не быть, тебе уже сказали
И что? Давай развивай тему, поговорим о системах с памятью в 4 Кб, о системах без мониторов, с вотчдогами, с 9 битами в байте. Разное бывает, дальше то что?
Здравствуйте, MTD, Вы писали:
L>>Ага, а как ты узнаешь поведение в случае, если ты хочешь открыть файл для чтения, а он — ридонли?
MTD>Сильно подозреваю, что он откроется нормально и его можно будет прочесть.
Сколько самолетов упало и сколько педалей газа заклинило из-за вот такого "сильно подозреваю"...
L>>Из документации только, как ты не расписывай API.
MTD>Что значит расписывай API? При чем тут документация, если мы комментарии в коде обсуждали?
Совершенно верно. Коменты в коде. Каждый юнит кода должен обосновывать свое существование, описывать, как он работает и почему он работает именно так, а не иначе и сообщать всю необходимую для его использования информацию.
L>>Еще раз — разные платформы имеют право вести себя по-разному. Это обязано быть отражено в документации.
MTD>Нет. Кроссплатформенная библиотека — абстракция над разными платформами, вести себя она должна одинаково иначе не понятно, зачем она нужна, проще нативные библиотеки использовать.
поведение файловой системы определяется платформой. Кроссплатформенная библиотека не всегда может или имеет право это поведение менять.
L>>Сектора и блоки ты сам сюда притащил. Это называется "довести до абсурда".
MTD>Ты с этого начал, я просто сказал, что логично ожидать, что функция с названием OpenFile не будет форматировать диск.
А вот что она будет делать при попытке открытия файла, которого нет? тут вариантов до чертиков и все они вполне логичные.
Здравствуйте, landerhigh, Вы писали:
L>>>Ага, а как ты узнаешь поведение в случае, если ты хочешь открыть файл для чтения, а он — ридонли?
MTD>>Сильно подозреваю, что он откроется нормально и его можно будет прочесть.
L>Сколько самолетов упало и сколько педалей газа заклинило из-за вот такого "сильно подозреваю"...
Во-первых, при разработке самолетов требования особые, если так разрабатывать обычный софт то он будет стоить неприемлемо дорого.
Во-вторых, поделись, что должно по-твоему произойти при открытии рид-онли файла на чтение?
В-третьих, проблемы надежности комментарии вообще никак не решают.
L>Совершенно верно. Коменты в коде.
Документация — это не комменты в коде.
L>Каждый юнит кода должен обосновывать свое существование, описывать, как он работает и почему он работает именно так, а не иначе и сообщать всю необходимую для его использования информацию.
Если цель осваивать бюджеты при нулевом выхлопе без такого не обойтись.
L>поведение файловой системы определяется платформой. Кроссплатформенная библиотека не всегда может или имеет право это поведение менять.
Значит библиотека не смогла предоставить адекватную абстракцию, то не нужна такая библиотека, надо использовать нативные.
L>А вот что она будет делать при попытке открытия файла, которого нет? тут вариантов до чертиков и все они вполне логичные.
Здравствуйте, MTD, Вы писали:
Z>>например мы реализовали какой-то сложный математический Z>>метод, нужен хотя бы комментарий, типа метод такой-то, см. статью такую-то, MTD>Это единственный случай когда в хорошем коде комментарий уместен.
Единственный? Завидую, но не верю.
Почти любая оптимизация нуждается в комментариях почему она ничего не ломает (это часто "нелогичное" отсутствие лишних проверок, локов и тыдытыпы).
Любой обход (workaround) нуждается в комментариях что именно мы чиним (железо? косяк чужой библиотеки?).
Кусок какого нибудь протокола (сеть? ipc?) с подозрением на нелогичность требует комментариев.
Иногда бывает что кажется будто есть более простые/логичные варианты реализации функции, комментарий почему сделано так, а не иначе — нужен.
Ну, понятно, что комментировать в стиле void *p = malloc(256); /* Allocates memory */ нафиг не надо.
Здравствуйте, landerhigh, Вы писали:
aik>>Ну, понятно, что комментировать в стиле void *p = malloc(256); /* Allocates memory */ нафиг не надо. L>Даже здесь нужен комментарий, объясняющий почему void, и почему именно maloc и что это за магическая константа.
Неа, вот тут как раз и не нужен, потому что код должен быть типа:
и никаких комментариев. И почему именно malloc — надо писать если это c++ или glibc (а лучше заменять на new/g_malloc), а если голый си + libc — то зачем это комментировать?
Здравствуйте, MTD, Вы писали:
L>>Сколько самолетов упало и сколько педалей газа заклинило из-за вот такого "сильно подозреваю"...
MTD>Во-первых, при разработке самолетов требования особые, если так разрабатывать обычный софт то он будет стоить неприемлемо дорого.
Сказки. При разработке самолетов обкладывание кода бумажками совершенно особое, но документацию разработчики читают самую обычную.
MTD>Во-вторых, поделись, что должно по-твоему произойти при открытии рид-онли файла на чтение?
Конечно, я хотел написать "открытие ридонли файла на чтение и запись". И вот что при этом произодйет, и должна объяснять документация к коду
MTD>В-третьих, проблемы надежности комментарии вообще никак не решают.
L>>Совершенно верно. Коменты в коде.
MTD>Документация — это не комменты в коде.
Это. Коменты в коде — это документация к коду. Если у вас иначе, то мне вас жаль.
L>>Каждый юнит кода должен обосновывать свое существование, описывать, как он работает и почему он работает именно так, а не иначе и сообщать всю необходимую для его использования информацию.
MTD>Если цель осваивать бюджеты при нулевом выхлопе без такого не обойтись.
То-то нулевой выхлоп при диких бюджетах наблюдается в основном при подходе "некогда документацию писать, копать надо"
Здравствуйте, landerhigh, Вы писали:
L>Сказки. При разработке самолетов обкладывание кода бумажками совершенно особое, но документацию разработчики читают самую обычную.
А ты для самолетов что писал? Вот мне довелось немного пописать критически важный код, там подходы к надежности совсем другие, например, софт пишут 3 независимые команды, затем в зависимости от входных данных 3 разные программы выдают результат, действие производится только если совпали все 3 результата, иначе чрезвычайная ситуация. Комментарии в коде безопасности никак не добавляют, гораздо лучше, например, ассертами описывать все контракты.
MTD>>Документация — это не комменты в коде.
L>Это. Коменты в коде — это документация к коду. Если у вас иначе, то мне вас жаль.
Покажи свой код, дабы не быть голословным. Доксигеновские описания — это никак не комментарии в коде, кроме того, для адекватной документации их мало.
L>>>Каждый юнит кода должен обосновывать свое существование, описывать, как он работает и почему он работает именно так, а не иначе и сообщать всю необходимую для его использования информацию.
MTD>>Если цель осваивать бюджеты при нулевом выхлопе без такого не обойтись.
L>То-то нулевой выхлоп при диких бюджетах наблюдается в основном при подходе "некогда документацию писать, копать надо"
Qbit86 меня обвинил в увлечении теории, когда я сказал, что комментарии в коде бардака не решат и надо думать как и что писать. Ты ударился в другую крайность — описывать вообще все. Извини, это ты менеджерам рассказывай, что все красиво оформлял, поэтому показать нечего, а я за взвешенный подход.
И не уходи от вопроса с которого началась дискуссия — адекватно функции открытия файла диск форматировать?
Говорить что код без комментариев плохой, также неверно как и говорить что комментарии не нужны.
Комментарии не всегда идут на пользу, точно также как не всегда оправданно и их отсутствие.
Неоднократно встречал как из комментариев делают карго-культ.
Например, возле пустого деструктора, который был абсолютно не нужен, стояло "это деструктор, он вызывается в конце жизни объекта" — и такого рода мусора по всему коду, перед каждой функцией, классом и строчкой кода, без всякой на то причины, аккуратненько так.
Такого рода комментарии как минимум раздражают, так как ожидаешь что-то осмысленное, несущее важную информацию — а там вода.
Комментарий это, очевидно, дополнительная сущность, которая отвлекает внимание, за которой нужно следить, держать в синхронизации с кодом.
Если комментарий не добавляет никакой новой информации способствующей пониманию кода, в то время как всё и так моментально ясно после беглого взгляда — то такой комментарий приносит вред.
Более того, нужно искать варианты замены комментария более простым и выразительным кодом. Тривиальный и классический пример — литерал с комментарием заменить константой с говорящим именем.
В то же время, при реализации каких-то нетривиальных концепций, с которыми читающий не обязан быть знаком, комментарии действительно необходимы.
В общем, как и всегда, нужно искать баланс и не допускать перекосы в ту или иную сторону
L>>Сказки. При разработке самолетов обкладывание кода бумажками совершенно особое, но документацию разработчики читают самую обычную.
MTD>А ты для самолетов что писал?
Прежде чем доставать линейку, предлагаю тебе подумать еще раз. А потом еще раз. А потом еще. Иначе конфуз получится.
MTD>Комментарии в коде безопасности никак не добавляют, гораздо лучше, например, ассертами описывать все контракты.
Имя того критически важного софта не затруднит привести? С ассертами.
MTD>>>Документация — это не комменты в коде.
L>>Это. Коменты в коде — это документация к коду. Если у вас иначе, то мне вас жаль.
MTD>Покажи свой код, дабы не быть голословным.
Коммерческая тайна.
MTD>Доксигеновские описания — это никак не комментарии в коде, кроме того, для адекватной документации их мало.
Значит, вы их готовить не умеете. Обычная ситуация, впрочем.
L>>>>Каждый юнит кода должен обосновывать свое существование, описывать, как он работает и почему он работает именно так, а не иначе и сообщать всю необходимую для его использования информацию.
MTD>>>Если цель осваивать бюджеты при нулевом выхлопе без такого не обойтись.
L>>То-то нулевой выхлоп при диких бюджетах наблюдается в основном при подходе "некогда документацию писать, копать надо"
MTD>Qbit86 меня обвинил в увлечении теории, когда я сказал, что комментарии в коде бардака не решат и надо думать как и что писать. Ты ударился в другую крайность — описывать вообще все. Извини, это ты менеджерам рассказывай, что все красиво оформлял, поэтому показать нечего, а я за взвешенный подход.
Это ты тут чего-то навыдумывал, приписал это собеседникам и теперь героически со своими же страхами борешься. Для начала потрудись доказать, что "красиво офомленный код" — это "нечего показать", что ли.
MTD>И не уходи от вопроса с которого началась дискуссия — адекватно функции открытия файла диск форматировать?
Не знаю, может быть для вашего свех-критического софта и адекватно
Здравствуйте, Evgeny.Panasyuk, Вы писали:
EP>Например, возле пустого деструктора, который был абсолютно не нужен, стояло "это деструктор, он вызывается в конце жизни объекта" — и такого рода мусора по всему коду, перед каждой функцией, классом и строчкой кода, без всякой на то причины, аккуратненько так.
Так бывает, когда требование о комментировании спускается сверху, а у разрабов нет даже зачатков инженерной культуры, чтобы понимать, зачем вообще нужны комментарии. И отсутствует лидер, который пряником, кнутом, огнем, мечом и инквизицией им эти зачатки привьет.
Я же сразу отметил бестолковость комментариев, присутствующих в коде, приведенном ТС и полное отсутствие комментариев там, где надо.
такая же история, кстати, случается и с юнит-тестами.
(хотя я сам комментирую объявление pure virtual destructor. На разный лад, а с определенной поры и на разных языках. Это моя фирменная фишка)
EP>Такого рода комментарии как минимум раздражают, так как ожидаешь что-то осмысленное, несущее важную информацию — а там вода.
EP>Комментарий это, очевидно, дополнительная сущность, которая отвлекает внимание, за которой нужно следить, держать в синхронизации с кодом. EP>Если комментарий не добавляет никакой новой информации способствующей пониманию кода, в то время как всё и так моментально ясно после беглого взгляда — то такой комментарий приносит вред.
Комментарий должен помогать в использовании кода. Кратко сообщать о том, что это за класс, зачем он нужен и как и в каких случаях используется, какие задачи решает, а какие-нет (в случае, если это неочевидно). Очень хорошо написать, какие паттерны используются. Хороший комментарий в заголовке класса убирает необходимость заглядывать в определение методов от слова совсем.
Здравствуйте, landerhigh, Вы писали:
MTD>>А ты для самолетов что писал?
L>Прежде чем доставать линейку, предлагаю тебе подумать еще раз. А потом еще раз. А потом еще. Иначе конфуз получится.
Это ты все мериться пытаешься, а я просто поинтересовался есть ли у тебя такой опыт. Так что думай.
L>Имя того критически важного софта не затруднит привести? С ассертами.
Билибинская, Курская, Ростовская АЭС. Но ассерты не для тех кто свято верит, что комментарии спасут от всего. Я же предпочитаю, что программа аварийно завершиться в случае нарушения контракта, чем будет функционировать непредсказуемо.
MTD>>Покажи свой код, дабы не быть голословным.
L>Коммерческая тайна.
Быстро слился.
MTD>>Доксигеновские описания — это никак не комментарии в коде, кроме того, для адекватной документации их мало.
L>Для начала потрудись доказать, что "красиво офомленный код" — это "нечего показать", что ли.
Будь добр, читай что пишешь, ничего не понятно.
MTD>>И не уходи от вопроса с которого началась дискуссия — адекватно функции открытия файла диск форматировать?
L>Не знаю, может быть для вашего свех-критического софта и адекватно
Здравствуйте, landerhigh, Вы писали:
L>Я же сразу отметил бестолковость комментариев, присутствующих в коде, приведенном ТС и полное отсутствие комментариев там, где надо.
Кстати да, я как раз о подобном и говорил — "CSewingDlg(CWnd* pParent = NULL); // стандартный конструктор".
L>такая же история, кстати, случается и с юнит-тестами.
Да, там тоже карго-культ цветёт и пахнет в виде каких-то формальных отписок.
L>(хотя я сам комментирую объявление pure virtual destructor. На разный лад, а с определенной поры и на разных языках. Это моя фирменная фишка)
Это, естественно, другого рода ситуация.
L>Комментарий должен помогать в использовании кода. Кратко сообщать о том, что это за класс, зачем он нужен и как и в каких случаях используется, какие задачи решает, а какие-нет (в случае, если это неочевидно).
Скажем так, мне трудно представить чем может быть вреден подобный комментарий для нетривиальных классов. Часто такой комментарий действительно оправдан, и даже необходим.
L>Очень хорошо написать, какие паттерны используются.
Смотря какого уровня класс, и что за паттерн. Например, комментировать что FooVisitor это "Visitor pattern" — избыточно, а вот сказать что обработка событий реализована как Proactor — уж точно ничем не повредит.
L>Хороший комментарий в заголовке класса убирает необходимость заглядывать в определение методов от слова совсем.
Кстати, немного offtopic — предпочитаю данные класса помещать в начало описания. Зачастую полезно знать не просто что делает класс, а представлять как именно он реализован, например чтобы оценить производительность/потребление ресурсов. Часто, краем глаза взглянув на структуру данных класса, сразу становится понятно что именно за птица и как она летает.
Здравствуйте, landerhigh, Вы писали:
L>Комментарий должен помогать в использовании кода. Кратко сообщать о том, что это за класс, зачем он нужен и как и в каких случаях используется, какие задачи решает, а какие-нет (в случае, если это неочевидно).
Имя класса должно быть выбрано удачно, тогда будет очевидно зачем он нужен.
Здравствуйте, MTD, Вы писали:
MTD>Это ты все мериться пытаешься, а я просто поинтересовался есть ли у тебя такой опыт. Так что думай.
L>>Имя того критически важного софта не затруднит привести? С ассертами.
MTD>Билибинская, Курская, Ростовская АЭС. Но ассерты не для тех кто свято верит, что комментарии спасут от всего. Я же предпочитаю, что программа аварийно завершиться в случае нарушения контракта, чем будет функционировать непредсказуемо.
Здравствуйте, Evgeny.Panasyuk, Вы писали:
L>>Я же сразу отметил бестолковость комментариев, присутствующих в коде, приведенном ТС и полное отсутствие комментариев там, где надо. EP>Кстати да, я как раз о подобном и говорил — "CSewingDlg(CWnd* pParent = NULL); // стандартный конструктор".
+
L>>такая же история, кстати, случается и с юнит-тестами. EP>Да, там тоже карго-культ цветёт и пахнет в виде каких-то формальных отписок.
и метрик вроде "покрытия кода тестами".
L>>Комментарий должен помогать в использовании кода. Кратко сообщать о том, что это за класс, зачем он нужен и как и в каких случаях используется, какие задачи решает, а какие-нет (в случае, если это неочевидно).
EP>Скажем так, мне трудно представить чем может быть вреден подобный комментарий для нетривиальных классов. Часто такой комментарий действительно оправдан, и даже необходим.
Есть еще важные вещи, которые зачастую не замечают или не придают им значения. Например, берет ли класс владение неким объектом или нет, а если нет, то должно ли гарантироваться время жизни этого объекта и как. Еще пример — случается, что в конструктор передается некий умный указатель, но он используется исключительно в конструкторе и не сохраняется в данных класса. Подобные вещи лучше всего добавлять в комментарии, чтобы минимизировать количество сюрпризов при использовании.
L>>Очень хорошо написать, какие паттерны используются.
L>>Хороший комментарий в заголовке класса убирает необходимость заглядывать в определение методов от слова совсем.
EP>Кстати, немного offtopic — предпочитаю данные класса помещать в начало описания. Зачастую полезно знать не просто что делает класс, а представлять как именно он реализован, например чтобы оценить производительность/потребление ресурсов. Часто, краем глаза взглянув на структуру данных класса, сразу становится понятно что именно за птица и как она летает.
ну, это уже дело привычки, и иногда может идти в разрез с принятыми в компании code conventions.
Здравствуйте, landerhigh, Вы писали:
L>Есть еще важные вещи, которые зачастую не замечают или не придают им значения. Например, берет ли класс владение неким объектом или нет, а если нет, то должно ли гарантироваться время жизни этого объекта и как.
Есть ряд типичных случаев, для которых есть общепринятые соглашения. В таких случаях комментарии не нужны.
А вот, например, если конструктор/метод берёт const Foo&, и сохраняет указатель в поле класса, то это нужно как-то обязательно обозначить.
L>Еще пример — случается, что в конструктор передается некий умный указатель, но он используется исключительно в конструкторе и не сохраняется в данных класса.
В таком случае нужно брать не умный указатель, а ссылку. Во-первых это бесплатно расширит область применимости, а во-вторых сделает комментарий необязательным (хотя и вреда он не принесёт).
L>Подобные вещи лучше всего добавлять в комментарии, чтобы минимизировать количество сюрпризов при использовании.
А вообще, да, нужно комментировать всякие неявные места, а иногда и явные, но не всем очевидные.
