Думаю сейчас все программисты используют системы автоматического документирования кода типа javadoc, когда к полям, методам и другим вещам можно писать комментарии в особом формате, который затем распознаётся IDE и системой документирования для создания документации. Это очень удобно, когда читаешь чужой код, наводишь мышкой на какой-то незнакомый метод и тебе в подсказке всплывает его описание, сразу становится всё ясно и не нужно лезть искать этот метод чтобы прочитать его код или доказываться по названию о его назначении, когда это может быть не очевидно. Есть и минусы. Главный минус я считаю это то что код, после снабжения такими комментариями для системы документирования, становится сложно читать, потому что комментариев там больше чем самого кода. Загляните в какой-нибудь файлик стандартной ява библиотеки. Брр. И второй минус, это то что для создания красивой документации приходится использовать всякие специфические конструкции в комментариях и даже html-теги, после чего сам по себе комментарий прочитать становится сложно, зато в выводе системы документирования или при наведении мышкой на переменной комментарий будет красивый.
Используете ли вы комментарии для систем документирования сразу по ходу кодирования или пишите их только в более ли менее готовом продукте, который будет лежать в каком-нибудь .jar-е с отдельно поставляемой документацией? Может вы их вообще не пишите если заказчик не требует документацию?
Ну и вообще кто что думает насчет минусов и плюсов про которые я писал Дискасс в общем.
Для нас [Thompson, Rob Pike, Robert Griesemer] это было просто исследование. Мы собрались вместе и решили, что ненавидим C++ [смех].
Использую .net. Пишу комментарии после завершения активной стадии разработки.
Основная проблема — при активной разработке комментарий быстро устаревает.
S> Ну и вообще кто что думает насчет минусов и плюсов про которые я писал Дискасс в общем.
Мне лично не хватает возможности аннотации кода по принципу добавления заметок в MS Word, например. Пишешь что-то и тут же бац — написал Note, описывающий, что ты делаешь.
S>Есть и минусы. Главный минус я считаю это то что код, после снабжения такими комментариями для системы документирования, становится сложно читать, потому что комментариев там больше чем самого кода.
Это смотря как их готовить. Комментари к объявлению функции на C++ с правильными альясами:
//x Что-то эта функция делает.
//r Описание возвращаемого значения.bool Foo(
//i Героический аргумент про который можно много всего хорошего
// и не очень написать.
QStringList items,
//o Краснознаменное возвращаемое значение, про которое тоже можно
// много всего написать, с ссылками на [CSomeModule], образцом
// использования кода:
// | if( ! VERIFY( Foo( QStringList() << "a" << "b", OUT result ) ) )
// | {
// | return;
// | }
// И чем нибудь еще нужным и полезным.
QStringList & result );
Что здесь нечитаемого?
S>Используете ли вы комментарии для систем документирования сразу по ходу кодирования или пишите их только в более ли менее готовом продукте, который будет лежать в каком-нибудь .jar-е с отдельно поставляемой документацией? Может вы их вообще не пишите если заказчик не требует документацию?
Я предпочитаю сразу все коментировать в нотаци, совместимой с извлекалками докуентаций. Хорошо время экономит.
S>Ну и вообще кто что думает насчет минусов и плюсов про которые я писал Дискасс в общем.
Минусы в том, что большинство современных языков разметки документаци в коде они какие-то... не для людей. Очень избыточный синтаксис . Приходится наворачивать над ними свои альясы как показано выше.
Здравствуйте, Sorc17, Вы писали:
S>...Главный минус я считаю это то что код, после снабжения такими комментариями для системы документирования, становится сложно читать, потому что комментариев там больше чем самого кода. Загляните в какой-нибудь файлик стандартной ява библиотеки. Брр....
Здравствуйте, Sorc17, Вы писали:
S>Используете ли вы комментарии для систем документирования сразу по ходу кодирования или пишите их только в более ли менее готовом продукте, который будет лежать в каком-нибудь .jar-е с отдельно поставляемой документацией? Может вы их вообще не пишите если заказчик не требует документацию?
Нет, не использую систем документирования, а сейчас и IDE не использую. Ну а так названия метода и имена параметров в большинстве случаев достаточно. А если недостаточно, то смотрим исходник. Для меня минусы перевешивают.
Более интересна идея литературного (literate) программирования.
Здравствуйте, Eye of Hell, Вы писали:
S>>Есть и минусы. Главный минус я считаю это то что код, после снабжения такими комментариями для системы документирования, становится сложно читать, потому что комментариев там больше чем самого кода.
EOH>Это смотря как их готовить. Комментари к объявлению функции на C++ с правильными альясами: EOH>
EOH>
EOH>Что здесь нечитаемого?
Всё.
За деревьями не видно кода.
Здравствуйте, Sorc17, Вы писали:
S>Думаю сейчас все программисты используют системы автоматического документирования кода типа javadoc
S>Используете ли вы комментарии для систем документирования сразу по ходу кодирования или пишите их только в более ли менее готовом продукте, который будет лежать в каком-нибудь .jar-е с отдельно поставляемой документацией? Может вы их вообще не пишите если заказчик не требует документацию?
Использую по привычке. Т.к. работаю с зарубежом, комментирую по английски для Doxygen. Вида:
//! This method do something
Пока обдумываю, что как реализовать метод или конструкции — пишу коменты.
S>Ну и вообще кто что думает насчет минусов и плюсов про которые я писал Дискасс в общем.
Главное не переборщить. У каждого своя мотивация писать комментарии. Вряд ли они пишутся для сопровождающих, если таких требований нет.
Здравствуйте, Banned by IT, Вы писали:
BBI>Здравствуйте, Mystic, Вы писали:
M>>Более интересна идея литературного (literate) программирования.
BBI>У нас тут один чел литературно багрепорты пишет. Порой нифига не понятно в чём именно проблема то.
Здравствуйте, Mystic, Вы писали:
M>>>Более интересна идея литературного (literate) программирования. BBI>>У нас тут один чел литературно багрепорты пишет. Порой нифига не понятно в чём именно проблема то. M>А это тут причем?
К тому, что очень уж это геморно получится.
Человек человека порой может неправильно понять, не говоря уже про компилятор.
EOH>>Что здесь нечитаемого? BBI>Всё. BBI>За деревьями не видно кода.
Можете привести пример документирования кода БЕЗ использования разметки системы автоматического документирования где бы за деревьями был хорошо виден код? Напоминаю, что вопрос топикстартера не о количестве и качестве комментариев, а о комментариях с разметкой для системы автоматического документирования.
Здравствуйте, Sorc17,
S>Ну и вообще кто что думает насчет минусов и плюсов про которые я писал Дискасс в общем.
--
Третий минус в том, что код и комментарии к нему могут потерять "синхронизацию".
Например, при изменении кода комментарии не изменились.
Здравствуйте, Eye of Hell, Вы писали:
EOH>Можете привести пример документирования кода БЕЗ использования разметки системы автоматического документирования где бы за деревьями был хорошо виден код? Напоминаю, что вопрос топикстартера не о количестве и качестве комментариев, а о комментариях с разметкой для системы автоматического документирования.
Комменты для системы автоматического докуменирования практически всегда засирают код.
EOH>>Можете привести пример документирования кода БЕЗ использования разметки системы автоматического документирования где бы за деревьями был хорошо виден код? Напоминаю, что вопрос топикстартера не о количестве и качестве комментариев, а о комментариях с разметкой для системы автоматического документирования.
BBI>Комменты для системы автоматического докуменирования практически всегда засирают код
Попробую еще раз — а можете привести пример комментов не для системы автомаического документирования, которые, по вашему мнению, код не засирают?
Здравствуйте, Eye of Hell, Вы писали:
EOH>Это смотря как их готовить. Комментари к объявлению функции на C++ с правильными альясами: EOH>
EOH>//x Что-то эта функция делает.
EOH>//r Описание возвращаемого значения.
EOH>bool Foo(
EOH> //i Героический аргумент про который можно много всего хорошего
EOH> // и не очень написать.
EOH> QStringList items,
EOH> //o Краснознаменное возвращаемое значение, про которое тоже можно
EOH> // много всего написать, с ссылками на [CSomeModule], образцом
EOH> // использования кода:
EOH> // | if( ! VERIFY( Foo( QStringList() << "a" << "b", OUT result ) ) )
EOH> // | {
EOH> // | return;
EOH> // | }
EOH> // И чем нибудь еще нужным и полезным.
EOH> QStringList & result );
EOH>
EOH>Что здесь нечитаемого?
Всё ! Код в 20-30 строчек превращается в 5-10 страниц и секундное дело превращается в получасовое листание страниц туда-обратно.
EOH>Я предпочитаю сразу все коментировать в нотаци, совместимой с извлекалками докуентаций. Хорошо время экономит.
Коментить лучше в отдельном репозитории для контрактов. комменты автоматически мерджатся с контрактами из рабочих бранчей и код не засоряется всяким говном.
EOH>>Что здесь нечитаемого? I>Всё ! Код в 20-30 строчек превращается в 5-10 страниц и секундное дело превращается в получасовое листание страниц туда-обратно.
Вы можете привести пример кода с комментариями не предназначенными для системы автоматической генерации докумнтации который вы оцениваете как читаемый?
I>Коментить лучше в отдельном репозитории для контрактов. комменты автоматически мерджатся с контрактами из рабочих бранчей и код не засоряется всяким говном.
А что им помешает рассинхронизироваться если они лежат в разных местах?
Здравствуйте, Eye of Hell, Вы писали:
I>>Всё ! Код в 20-30 строчек превращается в 5-10 страниц и секундное дело превращается в получасовое листание страниц туда-обратно.
EOH>Вы можете привести пример кода с комментариями не предназначенными для системы автоматической генерации докумнтации который вы оцениваете как читаемый?
Конечно. Смотри пример, декларативный код и комент только там где нет возможности выразить intention самим же кодом.
class XXXImportExport
{
...
public IPersistance Config()
{
var config = Config(Format.CSV).
Table(Chains).Into("Chains").When(ABC).Prompt("Chains ").
...
...
Table(Systems).Into("Systems").When(BCD).Prompt("Systems ");
return config;
}
private Table Chains()
{
var chains = from Network
...
...
...
select new { facility = fac, system = tSystem }; // chain нельзя экспортировать явно см. баг #нумерvar table = Table(input:chains, create:(ctx)=>ctx.Create<Chain>() )
...
...
...
.Column("ServerId").Export(x => x.system.ServerId).Import((x,v) => Import.ServerId(x,v));
return table;
}
I>>Коментить лучше в отдельном репозитории для контрактов. комменты автоматически мерджатся с контрактами из рабочих бранчей и код не засоряется всяким говном.
EOH>А что им помешает рассинхронизироваться если они лежат в разных местах?
Примерно как в коде — никто не в праве защитить репозиторий от умышленного нарушения кода.
Здравствуйте, Sorc17, Вы писали:
S>Используете ли вы комментарии для систем документирования сразу по ходу кодирования или пишите их только в более ли менее готовом продукте, который будет лежать в каком-нибудь .jar-е с отдельно поставляемой документацией? Может вы их вообще не пишите если заказчик не требует документацию?
Использую. Везде. Исключение — методы, реализующие интерфейс или переопределяющие методы родителя. Назначение комментариев — описать человекочитемый контракт метода. То, что можно передавать в качестве параметров, чего стоит и чего не стоит ожидать в результате поведения метода. При использовании учитывается контракт метода, а не его реализация в каком-либо классе. В процессе работы может обновляться комментарий без тела метода (какое-то поведение явно занесли в контракт или явно написали, что оно не определено), может меняться тело метода без комментария (изменилась реализация метода).
Плюсы/минусы. Читать не мешает. Такие комментарии (для системы документирования) в IDE имеют свой уникальный стиль и цвет и с кодом не путаются. Более того, "документация" отличается визуально и от обычных комментариев в коде, так что этой путаницы тоже нет. Рассинхронизация кода с контрактом не допускается никогда (ну за исключением ошибок). Потому что если где-то изменяется контракт, нужно проверить всех его пользователей (так как они могут полагаться на старое поведение). Если же допущена рассинхронизация, значит, где-то может быть ошибка (потому, что "пользователь" не ожидает изменившегося поведения). Писать комментарии не сложно — это всего лишь явная словесная формулировка контракта. Если контракт сформулировать сложно, значит, стоит подумать над классом/методом/переменной еще. Ну и в ряде случаев комментарий позволяет по месту посмотреть необходимую информацию (какие-то граничные случаи, детали поведения и т.п.).
. Приходится наворачивать над ними свои альясы как показано выше.
