Re[14]: Нужно ли документировать код?
От: IT Россия linq2db.com
Дата: 07.07.05 16:20
Оценка: 23 (1)
Здравствуйте, Кодт, Вы писали:

IT>>Нету. А ты используешь кросплатформенный COM?


К>Угу. Торнадовский VxDCOM, обработанный напильником (вот этими самыми руками).


Кстати, может попробовать таким же напильником обрабатывать tli и tlh файлы? Всё таки код генерируемый, может получится на него натравить регекспы и заменитть чем-нибудь несовместимые места.
... << RSDN@Home 1.1.4 stable rev. 510>>
Если нам не помогут, то мы тоже никого не пощадим.
Re[15]: Нужно ли документировать код?
От: Кодт Россия  
Дата: 07.07.05 16:26
Оценка:
Здравствуйте, IT, Вы писали:

IT>Кстати, может попробовать таким же напильником обрабатывать tli и tlh файлы? Всё таки код генерируемый, может получится на него натравить регекспы и заменитть чем-нибудь несовместимые места.


Хорошая мысля приходит опосля. Посмотрю, что из этого выйдет.
Перекуём баги на фичи!
Re[7]: Нужно ли документировать код?
От: Павел Кузнецов  
Дата: 07.07.05 17:04
Оценка: +2
eao197,

> Спасибо за подробный ответ. Я просто не представлял себе, что такая тривиальная задача, как контроль выбора пользователя из нескольких вариантов может привести к такому количеству ошибок. Чего, однако, в жизни не бывает.


Проблема в долгой жизни кода. В момент написания (обычно) ошибок в таких простых местах не делают. А вот когда начинается свистопляска с изменениями, да еще и через 2-3 и более лет после изначального написания, плюс целого ряда предшествовавших изменений, и уже давно не в том проекте, в который код входил изначально, и уже совсем не в том контексте... В общем, получается то, что получается. Без помощи компилятора очень легко пропустить какое-нибудь место, особенно, если один из исходников, где используется данная функция, не входит в текущий проект. А с учетом того, что обработку исключительных ситуаций тестировать сложнее, чем основное поведение, то и отлавливаются такие ошибки далеко не всегда. В итоге за время жизни кода, которое может легко и до 10 лет доходить, таки накапливаются ошибки. И ошибок тем больше, чем больше кода, который работает с данной подсистемой. В нашем случае функциональность, связанная с операциями, использующими communicators, является ядром проекта,
соответственно, кода вокруг этого дела вполне достаточно, плюс, в отличие от приведенных примеров, операции нетривиальны, а надежность обработки многообразных исключительных ситуаций очень важна, т.к. в противном случае пользователи легко потеряют свои данные.
Posted via RSDN NNTP Server 2.0 beta
Легче одурачить людей, чем убедить их в том, что они одурачены. — Марк Твен
Re[12]: Нужно ли документировать код?
От: Cyberax Марс  
Дата: 07.07.05 17:18
Оценка:
Кодт wrote:

> IT>http://www.rsdn.ru/article/vcpp/import.xml
Автор(ы): Игорь Ткачёв
Дата: 9.03.2001

В данной статье приводится объяснение работы директивы #import
компилятора Visual C++ и даны примеры её использования с
MS Word, MS Excel, ADO DB и ActiveX Control.

> <http://rsdn.ru/article/vcpp/import.xml&gt;
Автор(ы): Игорь Ткачёв
Дата: 9.03.2001

В данной статье приводится объяснение работы директивы #import
компилятора Visual C++ и даны примеры её использования с
MS Word, MS Excel, ADO DB и ActiveX Control.

> Спасибо. Жаль, что это чисто VC-шная штука. Или, может быть, есть
> кроссплатформенные тулзы?

Какая кроссплатформенность с COM?

Хотя есть Comet: http://lambdasoft.dk/Comet/ — оно собирается под GCC, и
вообще намного приятнее #import'а.

--
С уважением,
Alex Besogonov (alexy@izh.com)
Posted via RSDN NNTP Server 1.9
Sapienti sat!
Re[7]: Нужно ли документировать код?
От: Павел Кузнецов  
Дата: 07.07.05 18:13
Оценка:
eao197,

> E>> Да это-то я понимаю. Мне просто интересно, хорошо ли это? Нет ли здесь попытки замутить сознание в тривиальном, в общем-то, случае?


> К> Ничего себе тривиальный.


> Вообще-то я говорил именно про пример с "Нефиг, Нафиг, Пофиг" (т.е. Abort/Retry/Ignore). Имеет ли смысл наворачивать нетривиальные конструкции на шаблонах для таких тривиальных случаев? Будет ли это упрощение или, наоборот, усложнение кода? В конкретно том примере, который привел Павел, мне показалось, что применение шаблонов -- это overkill.


Ага... Кажется, я понял, где пример "недоплюнул" до реальной жизни...

Abort/Retry/Ignore — только один из возможных вариантов. И не факт, что завтра в этом же месте по-прежнему пользователю будет предоставлен именно такой выбор. Допустим, вчера было "Destination file exists. Abort/Retry/Ignore", а сегодня стало "Destination file exists. Replace? Abort/No/Yes", т.к. было решено, что так пользователю будет намного понятнее. Если код привязан непосредственно к вариантам, показываемым пользователю (Abort/Retry/Ignore vs. Abort/No/Yes), то все вообще плохо, т.к. вероятность внесения ошибок при последующих изменениях очень высока. Скажем, даже не изменяя варианты, можно изменить смысл некоторых из них, изменив вопрос, задаваемый пользователю: "Destination file exists. Skip? Abort/No/Yes", т.к., например, было решено, что предлагать деструктивное действие неправильно. (мотивация в данном случае берется с потолка, очевидно, что в реальной жизни причины бывают самые разные)

Соответственно, от "названий кнопок" нужно абстрагироваться обязательно, так чтобы функции-члены communicators, с которыми имеет дело логика операции, возвращали нечто в терминах операции, а не в терминах ответа пользователя: abort, skip, continue — вне зависимости от формулировок вопросов и предоставленных пользователю вариантов — означает, что, собственно, должна делать операция.

Но этого шага самого по себе недостаточно, т.к., как говорилось, доступные варианты действий могут меняться. Сегодня мы не умеем пропускать файлы при копировании, поэтому вариантов всего два (abort, continue), а завтра научимся — и нужно будет добавить еще один вариант (skip). Но мест, в которых содержится вызов данной функции, задающей вопрос пользователю, может быть много, соответственно, нужно обеспечить, чтоб поведение между всеми этими местами было согласованным.

Если же идти по другому пути — отдельная функция для каждого подобного места, — то ситуация тоже не лучше, в других аспектах: очень тяжело обеспечивать единообразие всех подобных случаев. Иначе пользователь может быть очень сильно удивлен, что в одном месте ему предлагают пропустить конфликтующий файл, а в другом — нет. Плюс, первоначальная проблема не решается в другом случае: реализаций данного интерфейса более одной (см. ниже), и, соответственно, нужно заботиться о соблюдении ими контракта (все реализации одной и той же функции должны возвращать согласованный набор результатов).

Если же идти еще по другому пути, не вводя прослойку в виде communicators, то мы не покроем целый ряд use cases, когда те же операции работают в несколько ином окружении, где с пользователем взаимодействовать нельзя, а варианты действий на все нештатные ситуации задаются заранее, скажем, опциями командной строки, конфигурационными файлами или еще как-нибудь. Плюс, мы намного осложним сопровождение кода, связав "логический" уровень с презентационным.

Приведенный подход решает все упомянутые проблемы.
Posted via RSDN NNTP Server 2.0 beta
Легче одурачить людей, чем убедить их в том, что они одурачены. — Марк Твен
Re[3]: Нужно ли документировать код?
От: Павел Кузнецов  
Дата: 07.07.05 18:38
Оценка:
eao197,

> ПК> Например, из свеженького.


> Вот этот бы классик, CommunicatorAnswer, да в виде реюзабильного шаблона, да в open-source виде получить, готовый. И в boost запихнуть.

>
> Чтобы самому велосипеды не плодить.

На самом деле, если идти дальше, то в общем случае одного значения enum в качестве результата выбора может быть недостаточно, вполне возможно, что, кроме кода выбранного варианта, желательно иметь какие-то дополнительные данные. Скажем, все на том же примере конфликтующих файлов при копировании, вполне может захотеться усложнить взаимодействие с пользователем и предоставить вариант скопировать файл под новым именем. В этом случае было бы разумно вернуть из Communicator в операцию это самое новое имя. Т.е. более общим подходом будет что-нибудь типа boost::variant параметризованный классами, представляющими соответствующие варианты действий. Часть из этих классов может быть пустой, просто обозначая сам выбор (например, Abort).

Собственно, в какой-то момент была предпринята попытка перейти от:
CommunicatorAnswer< communicator_abort | communicator_retry | communicator_ignore > answer;

к
boost::variant< CommunicatorAbort, CommunicatorSkip, CommunicatorOverwrite > answer;

но, к сожалению, в текущей реализации boost::variant обнаружился существенный для нашего use case недостаток: boost::variant не диагностирует во время компиляции извлечь из него значение, не входящее в список хранимых в нем типов. Т.е. для объявления выше следующее не приводит к ошибке компиляции:
if ( get< CommunicatorRename >( &answer ) )
   . . .

Также не выяснялся вопрос поддержки остальных описанных в теме use cases в boost::variant. Соответственно, пока переход к boost::variant отменен (*). Но в принципе, подход, основанный на использовании boost::variant или аналогичного класса мне кажется более общим и перспективным для данной задачи.

Собственно, пример с CommunicatorAnswer это пример того, как можно переводить комментарии в код, еще и получая целый ряд приятных бонусов. boost::variant или какой-нибудь более строгий аналог можно считать дальнейшим развитием этого подхода, и идее явного задания контрактов в коде он не противоречит, скорее ее дополняет...

В любом случае, классик можно и выложить куда-нибудь, т.к., фактически, его использование не сводится к данной задаче, и он может оказаться полезным в любой другой ситуации наборов значений, из которых в разные моменты нужно работать только с некоторым подмножеством, и верифицировать все это дело во время компиляции.



(*) Хотя есть достаточно дешевые способы сделать к нему свои переходники, исправляющие найденные недочеты, но о них мысли появились уже потом — может, когда понадобится возвращать что-нибудь, кроме кода сделанного выбора, все-таки к нему и перейдем. Может, к тому времени он даже будет исправлен нужным образом
Posted via RSDN NNTP Server 2.0 beta
Легче одурачить людей, чем убедить их в том, что они одурачены. — Марк Твен
Re[4]: Нужно ли документировать код?
От: bkat  
Дата: 07.07.05 19:13
Оценка:
Здравствуйте, Павел Кузнецов, Вы писали:


ПК>У меня с документацией, подобной бустовской, не ассоциируется слово "код" в том смысле, что для меня это не документирование кода


Хорошо, документация, подобной бустовской — это конечно больше manual.
Что тогда "документирование кода"?
Неужто только комментарии и красивый код сам по себе?
Re[5]: Нужно ли документировать код?
От: Павел Кузнецов  
Дата: 07.07.05 20:04
Оценка:
bkat,

> ПК> У меня с документацией, подобной бустовской, не ассоциируется слово "код" в том смысле, что для меня это не документирование кода

>
> Хорошо, документация, подобной бустовской — это конечно больше manual.
> Что тогда "документирование кода"?
> Неужто только комментарии и красивый код сам по себе?

Я различаю "документирование кода" и "комментирование кода" только местом размещения документации: в первом случае это может быть не только в комментариях непосредственно в исходном коде, но и где-то еще. Другое дело, что, кроме документирования кода, может потребоваться и другая документация, относящаяся к процессу разработки: требования, спецификация, документация окружения, документ, описывающий соглашения о кодировании, всевозможные rationale для архитектурных решений т.д., и т.п.
Posted via RSDN NNTP Server 2.0 beta
Легче одурачить людей, чем убедить их в том, что они одурачены. — Марк Твен
Re[2]: Нужно ли документировать код?
От: VladD2 Российская Империя www.nemerle.org
Дата: 08.07.05 17:14
Оценка:
Здравствуйте, Павел Кузнецов, Вы писали:

Почему был не завести два перечисления?

Что же до символов в качестве результата функции, то за такое морду нужно бить (сильно).
... << RSDN@Home 1.1.4 beta 7 rev. 466>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Re[11]: Нужно ли документировать код?
От: VladD2 Российская Империя www.nemerle.org
Дата: 08.07.05 17:14
Оценка: :)
Здравствуйте, IT, Вы писали:

IT>http://www.rsdn.ru/article/vcpp/import.xml
Автор(ы): Игорь Ткачёв
Дата: 9.03.2001

В данной статье приводится объяснение работы директивы #import
компилятора Visual C++ и даны примеры её использования с
MS Word, MS Excel, ADO DB и ActiveX Control.


Я вот подумал... прикинь как мы раньше мучались. А ведь многие и до сих пор над собой издеваются.
... << RSDN@Home 1.1.4 beta 7 rev. 466>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Re[12]: Нужно ли документировать код?
От: VladD2 Российская Империя www.nemerle.org
Дата: 08.07.05 17:14
Оценка:
Здравствуйте, Кодт, Вы писали:

К>Спасибо. Жаль, что это чисто VC-шная штука. Или, может быть, есть кроссплатформенные тулзы?


Борланд частично поддерживает. Но это дело генерирует обертки на чистом С++ вроде бы.
... << RSDN@Home 1.1.4 beta 7 rev. 466>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Re[3]: Нужно ли документировать код?
От: Павел Кузнецов  
Дата: 08.07.05 17:28
Оценка:
VladD2,

> Почему был не завести два перечисления?


Этого недостаточно: не будут диагностироваться ошибки, связанные с расширением этих перечислений. http://rsdn.ru/forum/?mid=1263523
Автор: Павел Кузнецов
Дата: 08.07.05
Posted via RSDN NNTP Server 2.0 beta
Легче одурачить людей, чем убедить их в том, что они одурачены. — Марк Твен
Re[3]: Нужно ли документировать код?
От: achp  
Дата: 08.07.05 17:32
Оценка:
Здравствуйте, VladD2, Вы писали:

VD>Что же до символов в качестве результата функции, то за такое морду нужно бить (сильно).


И разработчикам lex и yacc тоже?
Re[13]: Нужно ли документировать код?
От: IT Россия linq2db.com
Дата: 08.07.05 18:25
Оценка:
Здравствуйте, VladD2, Вы писали:

К>>Спасибо. Жаль, что это чисто VC-шная штука. Или, может быть, есть кроссплатформенные тулзы?


VD>Борланд частично поддерживает. Но это дело генерирует обертки на чистом С++ вроде бы.


Импорт использует расширение компилятора для объявления пропертей.
... << RSDN@Home 1.1.4 stable rev. 510>>
Если нам не помогут, то мы тоже никого не пощадим.
Re[14]: Нужно ли документировать код?
От: VladD2 Российская Империя www.nemerle.org
Дата: 08.07.05 20:48
Оценка:
Здравствуйте, IT, Вы писали:

IT>Импорт использует расширение компилятора для объявления пропертей.


Ну, это макросами лечится. К тому же борланд и многие другие вроде их тоже поддерживают.
... << RSDN@Home 1.1.4 beta 7 rev. 466>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Re[4]: Нужно ли документировать код?
От: VladD2 Российская Империя www.nemerle.org
Дата: 08.07.05 20:48
Оценка:
Здравствуйте, Павел Кузнецов, Вы писали:

ПК>Этого недостаточно: не будут диагностироваться ошибки, связанные с расширением этих перечислений. http://rsdn.ru/forum/?mid=1263523
Автор: Павел Кузнецов
Дата: 08.07.05


А что гарантирует от того, что в if новые элементы незабудут впихнуть?

Это что, такая извращенная замена контекстному поиску? Ну, изменяй названия типа когда добавляешь новые элементы. Эффект будет тот же.

ЗЫ

Если уж волнует согласованность изменений, то есть только два 100%-ых способа:
1. Довести все до декларативности избавишись от необходимости описывать что-то в двух местах. Так, например, сделаны меню и тулбары в Хоуме.
2. Иметь некоторые средства тестирования позволяющих описать правила проверки. Ну, ты полян на что я намекаю.

А это все примочки. Да и банальный дефолт в свитче в рантайме выдаст исключение. А синтаксис у тебя получается ужастным. Копипэст чистой воды, да еще и длинный как черт знает что.
... << RSDN@Home 1.1.4 beta 7 rev. 466>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Re[4]: Нужно ли документировать код?
От: VladD2 Российская Империя www.nemerle.org
Дата: 08.07.05 20:48
Оценка:
Здравствуйте, achp, Вы писали:

VD>>Что же до символов в качестве результата функции, то за такое морду нужно бить (сильно).


A>И разработчикам lex и yacc тоже?


Ты действительно не понял о чем я говрил?
... << RSDN@Home 1.1.4 beta 7 rev. 466>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Re[15]: Нужно ли документировать код?
От: IT Россия linq2db.com
Дата: 08.07.05 20:54
Оценка:
Здравствуйте, VladD2, Вы писали:

IT>>Импорт использует расширение компилятора для объявления пропертей.


VD>Ну, это макросами лечится. К тому же борланд и многие другие вроде их тоже поддерживают.


У них у всех свои расширения.
... << RSDN@Home 1.1.4 stable rev. 510>>
Если нам не помогут, то мы тоже никого не пощадим.
Re[5]: Нужно ли документировать код?
От: Павел Кузнецов  
Дата: 08.07.05 22:24
Оценка: +1
VladD2,

> ПК>Этого недостаточно: не будут диагностироваться ошибки, связанные с расширением этих перечислений. http://rsdn.ru/forum/?mid=1263523
Автор: Павел Кузнецов
Дата: 08.07.05

>
> А что гарантирует от того, что в if новые элементы незабудут впихнуть?

Ничего, но это уже совсем другое дело: если человек меняя тип локальной переменной, не просмотрит тут же присутствующие места, где она используется, то с тем же успехом оно может и пустую ветку if добавить. Это уже халатность. При изменении кода необходимо верифицировать корректность предусловий, при изменении предусловий — корректность кода...

> Это что, такая извращенная замена контекстному поиску? Ну, изменяй названия типа когда добавляешь новые элементы. Эффект будет тот же.


Не будет. Забыть изменить название можно полениться, или не знать о том, что это нужно делать. Тут код полностью направляет в правильном направлении. Плюс, изменение имен типов не решает проблем с объединением наборов значений, как уже было описано ранее.

> А это все примочки. Да и банальный дефолт в свитче в рантайме выдаст исключение.


Уже несколько раз было сказано, почему именно проверки во время исполнения недостаточны.

В общем, если хочешь привести конкретный пример более удачного решения описанной проблемы — давай, я с удовольствием посмотрю. Иначе я обсуждение со своей стороны заканчиваю.
Posted via RSDN NNTP Server 2.0 beta
Легче одурачить людей, чем убедить их в том, что они одурачены. — Марк Твен
Re[5]: Нужно ли документировать код?
От: achp  
Дата: 10.07.05 18:04
Оценка:
Здравствуйте, VladD2, Вы писали:

VD>Ты действительно не понял о чем я говрил?


О неком непреложном правиле. Нет?
Подождите ...
Wait...
Пока на собственное сообщение не было ответов, его можно удалить.