Вышел новый Visual Assist

[kika]

Для тех кто не в курсе, это такая довольно глючная и дорогая как самолет фигулина, которая из MS Visual Studio делает бледное подобие Эклипса или IDEA.
Не прошло и пяти лет как НебитыеПомидоры изобрели рефакторинг. Сижу, читаю про этот рефакторинг, и в конце там есть абзац про то что VAX нынче умеет автоматично документировать методы. То есть по нажатию кнопули генерит что-то типа

Я вот второй день пытаюсь понять - а зачем это? Вот что такого написано в первых 10-ти строчках, чего не написано в 11-ой? Разве что квалификатор public. Вообще, люди, которые называют это "документированием кода" и придумали такую "документацию", они как, головным мозгом оснащены или все же конструкцией не предусмотрено? Типа как поворотники у Волги?

UPD: Имеет место быть непонимание. Я знаю зачем нужна документация хотя бы на "экспортируемый" код и вообще знаю зачем нужно документировать. И я сам пользуюсь частично автоматично сгенерированной документацией (Qt). Я не это спрашивал. Я спрашивал зачем нужна конкретно вот эта вот (ну или аналогичная) хуйня, которую генерирует VAX в виде якобы заготовки документации. Информационно он мог бы генерировать /* */ и это было бы ровно тоже самое.

Comments

[evolver.livejournal.com]

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

[kika.livejournal.com]

Да запросто. Что мешает этому парсеру достать ровно тоже самое прям из декларации функции?

[evolver.livejournal.com]

По сути - ничто не мешает. Разве что парсер посложнее будет. Но все равно смысла в таком комментировании не вижу, несмотря на то, что похожий стиль долгое время был нашим корпоративным coding standard. Хорошо, что больше это не так.

[rblaze.livejournal.com]

Парсер называется doxygen, не такой уж примитивный и требует комментариев в другом формате :)

[jsn.livejournal.com]

возможно, идея в том, что ты потом напротив nRow в сгенерённой строчке приписываешь на своём родном чешском языке: "specify '-123456' to force coredump".

[kika.livejournal.com]

Ну я бы лично в таком случае написал бы сразу после
{
что-то типа
QPL_FORCECORE(nRow == -123456);
Как и граничные условия для параметров я стараюсь документировать ассертами или обычными проверками (но ассерты как-то эксплицитнее).

Такой метод писания документации хорош еще и тем что он более typesafe. Если я поменяю тип nRow на unsigned, то умному ассисту может хватить ума поменять тип в "документации", но вот отрицательное значение в чешской фразе он вряд ли поймет. А QPL_FORCECORE сгенерирует ворнинг.

Вообще, имхо, такого типа документация похоже предназначена для людей, которые будут читать код не понимая языка программирования, на котором он написан. Жажду объяснений от почтенной публики зачем бы это было надо?
При том что существуют люди, которые вот эту вот белиберду пишут даже не автоматичными средствами, а вручную.

[dz.livejournal.com]

Я туплю - ты javadoc-ов не видел????

[kika.livejournal.com]

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

Программа - живое существо. Зачем в живое существо натыкивать мертвого пластика? Пластик не растет и не изменяется, а программист вместо программирования начинает заниматься литературным трудом. Об отличиях одного от другого, кстати, написал только что Грэм.

Представим себе что мы живем в доме, где на каждом архитектурно-инженерном элементе написано что это такое. Пол, стена, балка, унитаз, петля, ручка, розетка и т.д. Интересно, психически уравновешенный человек долго продержится? И это ведь еще облегченный вариант, по-настоящему должно быть "стена 4х3м с пятью дырками 8мм на высоте 1.5м от [a href=floor.doc]пола[/a], etc, etc, etc". И про просверливании дырки под картинку надо было бы пройти по цепочке и проапдейтить все описания.

[dz.livejournal.com]

Ну, как бы, наличие явадока не мешает лазить в код, в принципе. А отставание его от кода - тоже большой и интересный вопрос - по хорошему, если меняется не _реализация_ (это не требует апдейта описания) а _суть_ метода, то хорошо бы делать другой метод. То есть тут, по идее, не док виноват.

Я понимаю и в целом разделяю твою позицию, но это некоторый максимализм. Есть вещи, которые не укладываются ни в название метода, ни в список параметров, ни в ассёрты. Да и просто искать там по коду, с какого бодуна оно кидает эксепшн X - не фонтан.

[kika.livejournal.com]

> Ну, как бы, наличие явадока не мешает лазить в код, в принципе.

Здрасьте, не мешает. Hot fucking news.
Смотрим опять на скриншот. Коэффициент полезного действия 1/11ая, меньше 10%. Это конечно передерг, потому что кода там ровно одна строчка, но у меня регулярно встречаются методы по 10-15 строк, на которых КПД использования screen estate получается чуть больше 50%. Я понимаю что современные редакторы, специально приспособленные для таких уебков-программистов, имеют режим скрывания комментариев. Это отлично же! Сначала автоматично пишем, потом скрываем и никогда больше не показываем. А читает это только опять автоматичный скрипт, который генерирует документацию, которую уже совсем никто не читает, потому что ничего полезного там не написано (ибо некем). Зато, бля, индустриально произведенный код! Не выебем, так хоть согреемся.

> если меняется не _реализация_ (это не требует апдейта описания) а _суть_ метода, то хорошо бы делать другой метод.

ОК, меняется реализация. Например метод sort(). Сортирует bidirectional iterator. Тут мы меняем немного алгоритм и наш сорт() теперь требует рандом итератор. Че, назовем его randomSort(), да?

И вообще, ты что, на самом деле пишешь в комментарии почему метод кидает эксепшн? А в код ты при этом это писать не забываешь? Я б точно забыл. Я пишу в код, а если мне хочется узнать когда оно это бросает я набираю в редакторе /throw X
Еще раз - я плохой английский читаю медленнее чем даже плохой С++. Думаю что и хороший английский тоже.

[dz.livejournal.com]

фиг его знает, как оно там у вас в С++... я, признаться, редко пользуюсь итераторами. Очень... А эксепшны - да, документирую. Но не в коде - там обычно действительно очевидно.

[jsn.livejournal.com]

да не, я, в общем, согласен, я просто тоже пытаюсь понять инопланетную логику.

[msh.livejournal.com]

Да затем же зачем венгерская нотация. Дешевая имитация. Думать не надо и вроде как документация есть