Думаю сейчас все программисты используют системы автоматического документирования кода типа 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 имеют свой уникальный стиль и цвет и с кодом не путаются. Более того, "документация" отличается визуально и от обычных комментариев в коде, так что этой путаницы тоже нет. Рассинхронизация кода с контрактом не допускается никогда (ну за исключением ошибок). Потому что если где-то изменяется контракт, нужно проверить всех его пользователей (так как они могут полагаться на старое поведение). Если же допущена рассинхронизация, значит, где-то может быть ошибка (потому, что "пользователь" не ожидает изменившегося поведения). Писать комментарии не сложно — это всего лишь явная словесная формулировка контракта. Если контракт сформулировать сложно, значит, стоит подумать над классом/методом/переменной еще. Ну и в ряде случаев комментарий позволяет по месту посмотреть необходимую информацию (какие-то граничные случаи, детали поведения и т.п.).
Здравствуйте, Banned by IT, Вы писали:
BBI>К тому, что очень уж это геморно получится. BBI>Человек человека порой может неправильно понять, не говоря уже про компилятор.
Здравствуйте, Banned by IT, Вы писали:
BBI>Человек человека порой может неправильно понять, не говоря уже про компилятор.
Компилятор получает на вход программу. Что он там может понять неправильно??? Человек видит статью, которая описывает то, как работает программа. Тут же рядом исходник. Какие могут быть проблемы???
EOH>>Вы можете привести пример кода с комментариями не предназначенными для системы автоматической генерации докумнтации который вы оцениваете как читаемый?
I>Конечно. Смотри пример, декларативный код и комент только там где нет возможности выразить intention самим же кодом.
Насколько я понимаю топикстартера, вопрос не а том "писать комменты или писать самодокументированный код" а "писать комменты для системы автогенерации документации или писать комменты не для системы автогенерации документации". Или я не прав?
BTW, приведенный вами пример — это внутренности программы. Комментарии обычно массово пишут для торчащего наружу API / точек взаимодействий модулей.
Здравствуйте, Ikemefula, Вы писали:
I>Коментить лучше в отдельном репозитории для контрактов. комменты автоматически мерджатся с контрактами из рабочих бранчей и код не засоряется всяким говном.
Очень интересный подход. Я даже о таком не думал.
Для нас [Thompson, Rob Pike, Robert Griesemer] это было просто исследование. Мы собрались вместе и решили, что ненавидим C++ [смех].
Здравствуйте, Eye of Hell, Вы писали:
BBI>>Комменты для системы автоматического докуменирования практически всегда засирают код EOH>Попробую еще раз — а можете привести пример комментов не для системы автомаического документирования, которые, по вашему мнению, код не засирают?
Скопипастить сюда понятное дело не могу.
А так: комменты ровно там, где они нужны. Для пояснения зачем и почему.
Здравствуйте, Eye of Hell,
ГМ>>Третий минус в том, что код и комментарии к нему могут потерять "синхронизацию". ГМ>>Например, при изменении кода комментарии не изменились.
EOH>Соответствено чем ближе комментарии к коду, тем меньше шанс на рассинхронизацию?
--
Нет, не так.
IMHO, между расстоянием код/комментарий и шансом на рассинхронизацию особой связи нет.
BBI>Скопипастить сюда понятное дело не могу. BBI>А так: комменты ровно там, где они нужны. Для пояснения зачем и почему.
Насколько з знаю, системы автоматической генерации документации обычно используются для публичных API. С вашей точки зрения — публичные API это "ровно то место" где комменты нужны или "не ровно"?
Здравствуйте, Ikemefula, Вы писали:
I>Конечно. Смотри пример, декларативный код и комент только там где нет возможности выразить intention самим же кодом.
I>
I> class XXXImportExport
I> {
I> ...
I> public IPersistance Config()
I> {
I> var config = Config(Format.CSV).
I> Table(Chains).Into("Chains").When(ABC).Prompt("Chains ").
I> ...
I> ...
I> Table(Systems).Into("Systems").When(BCD).Prompt("Systems ");
I> return config;
I> }
I> private Table Chains()
I> {
I> var chains = from Network
I> ...
I> ...
I> ...
I> select new { facility = fac, system = tSystem }; // chain нельзя экспортировать явно см. баг #нумер
I> var table = Table(input:chains, create:(ctx)=>ctx.Create<Chain>() )
I> ...
I> ...
I> ...
I> .Column("ServerId").Export(x => x.system.ServerId).Import((x,v) => Import.ServerId(x,v));
I> return table;
I> }
I>
Посмотрел. Зачем нужен XXXImportExport, что делает Config, что делает Chains? Ты в теме, тебе это понятно. А я вижу этот кусок первый раз и не знаю этого. Чтобы ответить на эти вопросы, не читая кода, и нужны комментарии к методам и классам.
Сравни
/*!
Constructs a bitmap that is a copy of the given \a pixmap.
If the pixmap has a depth greater than 1, the resulting bitmap
will be dithered automatically.
\sa QPixmap::depth(), fromImage(), fromData()
*/
QBitmap::QBitmap(const QPixmap &pixmap)
{
QBitmap::operator=(pixmap);
}
Здравствуйте, enji, Вы писали:
E>Посмотрел. Зачем нужен XXXImportExport,
XXXImportExport делает XXX импорт и XXX экспорт
>что делает Config,
задаёт конфиг для XXX импорт и XXX экспорт
>что делает Chains?
Задаёт конфиг для XXX импорта-экспорта Chains(бизнес-сущность такая).
>Ты в теме, тебе это понятно. А я вижу этот кусок первый раз и не знаю этого.Чтобы ответить на эти вопросы, не читая кода, и нужны комментарии к методам и классам.
Если ты начинаешь работу с проектом, придется познакомиться с бизнес-сущностями, задачами и тд и тд.
E>Сравни
Несерьёзный пример. Я тебе привел пример из бизнес-задачи, а ты мне сунул битмапы, т.е. к бизнесу никакого отношения
Но очевидно, в низкоуровневом программировании это съест перформанс и только это может быть оправданием твоим каментам.
Кроме того, человек, который не работал с рендерингом, и ничего не знает про pixmap, bitmap, depth и dithering, будет смеотреть на твой камент как на китайскую грамоту.
"Ты в теме, тебе это понятно. А я вижу этот кусок первый раз и не знаю этого..." Только в твоём случае нудно раздраконить вообще всё внутренности, а в моём в кишки лезть не надо. Любой, кто знаком с таким подходом как Fluent интерфейс, поймёт что к чему и как правило в методы вроде When, Where, Into лезть вообще не надо.
Здравствуйте, Ikemefula, Вы писали:
I>Здравствуйте, enji, Вы писали:
E>>Посмотрел. Зачем нужен XXXImportExport,
I>XXXImportExport делает XXX импорт и XXX экспорт
импорт и экспорт — очень расплывчатые понятия на самом то деле. Не помешало бы ссылка на описание этого процесса — зачем он нужен, как его использовать и т.д.
>>что делает Config,
I>задаёт конфиг для XXX импорт и XXX экспорт
Что такое конфиг, что с ним делать, что в нем должно лежать?
>>Ты в теме, тебе это понятно. А я вижу этот кусок первый раз и не знаю этого.Чтобы ответить на эти вопросы, не читая кода, и нужны комментарии к методам и классам.
I>Если ты начинаешь работу с проектом, придется познакомиться с бизнес-сущностями, задачами и тд и тд.
Ага, но вот только одно дело — читать описания бизнес сущностей на человеческом языке, и совсем другое — восстанавливать эти описания из кода. По твоему коду, например, описания не восстанавливаются. Наверное их можно восстановить, но для этого надо рассмотреть, что именно происходит в твоих методах, а также в методах, использующих эти методы. КОмментарий значительно упрощает жизнь.
I>Несерьёзный пример. Я тебе привел пример из бизнес-задачи, а ты мне сунул битмапы, т.е. к бизнесу никакого отношения
А тема разве про комментирование бизнес-задач?
I>И я бы выкинул каменты и оставил нечто вроде:
Ну дык с однострочным методом просто. А теперь посмотри на кучу своего кода I>
I>Но очевидно, в низкоуровневом программировании это съест перформанс и только это может быть оправданием твоим каментам.
Ну дык тут однострочный метод. РАссмотри свой крутой высокоуровневый метод на полэкрана (даже в поскипанном виде), из которого нифига не ясно . Подозреваю его тож можно переписать так, чтобы понятно было несколько больше. Ну а можно просто добавить комментарий.
I>Кроме того, человек, который не работал с рендерингом, и ничего не знает про pixmap, bitmap, depth и dithering, будет смеотреть на твой камент как на китайскую грамоту.
Да, поэтому есть коммент, а в нем — ссылки, куда смотреть. В сгенеренной доке по ссылкам можно добраться в том числе и до разжеванных описаний.
I>"Ты в теме, тебе это понятно. А я вижу этот кусок первый раз и не знаю этого..." Только в твоём случае нудно раздраконить вообще всё внутренности, а в моём в кишки лезть не надо. Любой, кто знаком с таким подходом как Fluent интерфейс, поймёт что к чему и как правило в методы вроде When, Where, Into лезть вообще не надо.
Дело не в When/where, а в том, какую задачу решает этот метод, как его правильно применять и т.д. Из твоих кишок и названия метода все это не очевидно.
Здравствуйте, enji, Вы писали:
I>>XXXImportExport делает XXX импорт и XXX экспорт
E>импорт и экспорт — очень расплывчатые понятия на самом то деле. Не помешало бы ссылка на описание этого процесса — зачем он нужен, как его использовать и т.д.
Если ты приходишь на конкретный проект, то приходится осваивать бизнес-специфику. Импорт это всегда перенос готовых из внешнего мира в рассматриваемую систему. Экспорт — это перенос готовых данных из системы во внешний мир. Зачем нужен импорт-экспорт и что такое XXX — это всё в ТЗ и UML. Dыносить это в каменты нет никакой необходимости.
I>>задаёт конфиг для XXX импорт и XXX экспорт E>Что такое конфиг, что с ним делать, что в нем должно лежать?
конфигурация Если ты не понимаешь, что такое импорт, экспорт и конфигурация то тебе нечего делать на таком проекте. Ну или проходить ликбез.
I>>Если ты начинаешь работу с проектом, придется познакомиться с бизнес-сущностями, задачами и тд и тд. E>Ага, но вот только одно дело — читать описания бизнес сущностей на человеческом языке, и совсем другое — восстанавливать эти описания из кода.
По человечески бизнес сущности придется описывать неодним десятком страниц текста. Есть ТЗ, UML и всякие доки, вот там и будет необходимое описание. В коде же вместо
IterateOverArrayWithDataReceivedOnPreviousStepAndIfYYYHasZZZDoSomeSteps нужно писать SelectUnroutedFacilities.
>По твоему коду, например, описания не восстанавливаются. Наверное их можно восстановить, но для этого надо рассмотреть, что именно происходит в твоих методах, а также в методах, использующих эти методы. КОмментарий значительно упрощает жизнь.
Код и не предназначен для восстановления описаний. Он предназначен для того, что бы все кишки были заданы гибко и наглядно для того, кто освоил бизнес-специфику.
Что бы дать определение что такое Chain нужно привести всю диаграму связей и операций с эти Сhain — нахрена это надо в коде, если есть UML ?
I>>Несерьёзный пример. Я тебе привел пример из бизнес-задачи, а ты мне сунул битмапы, т.е. к бизнесу никакого отношения E>А тема разве про комментирование бизнес-задач?
Ты пойми простую вещь, битмап и пиксмап известны всем, кто имел дела с рендерингом. Но это не значит, что любой сможет из твоего кода разобраться что такое и для чего нужны битмапы и прочая дрянь. По этой причине в твоём коде рвно тоже что и уменя, за исключением двух неразрешимых проблем.
E>Ну дык с однострочным методом просто. А теперь посмотри на кучу своего кода I>>
I>>Но очевидно, в низкоуровневом программировании это съест перформанс и только это может быть оправданием твоим каментам. E>Ну дык тут однострочный метод.
Это когда ты сидишь носом в этом коде, тебе всё просто и понятно. А реально надо знать все кишки. Разница у меня и у тебя в том, что кишки задаются декларативно, а у тебя придется мотаться по всем методам.
Итого у тебя однострочный метод скрывает все необходимые детали, а у меня пол-экрана содержат полное решение бизнес-задачи.
>РАссмотри свой крутой высокоуровневый метод на полэкрана (даже в поскипанном виде), из которого нифига не ясно . Подозреваю его тож можно переписать так, чтобы понятно было несколько больше. Ну а можно просто добавить комментарий.
Вероятно, тот факт, что декларативный код даёт меньше ошибок, для тебя новость
I>>Кроме того, человек, который не работал с рендерингом, и ничего не знает про pixmap, bitmap, depth и dithering, будет смеотреть на твой камент как на китайскую грамоту. E>Да, поэтому есть коммент, а в нем — ссылки, куда смотреть. В сгенеренной доке по ссылкам можно добраться в том числе и до разжеванных описаний.
В итоге секундное действие превращается вполчаса перелистывания.
I>>"Ты в теме, тебе это понятно. А я вижу этот кусок первый раз и не знаю этого..." Только в твоём случае нудно раздраконить вообще всё внутренности, а в моём в кишки лезть не надо. Любой, кто знаком с таким подходом как Fluent интерфейс, поймёт что к чему и как правило в методы вроде When, Where, Into лезть вообще не надо.
E>Дело не в When/where, а в том, какую задачу решает этот метод, как его правильно применять и т.д. Из твоих кишок и названия метода все это не очевидно.
Другой пример. Если ты не в курсе конечных автоматов, то тебе без толку декларативное задание конечного автомата. Но твой код со ссылками и каментами ничем не лучше.
ДЕкларативный код вроде того что я показал, нужен тому, кто знает что такое КА и ему не надо будет мотаться по страницам и вычитывать каменты что бы понять что к чему.
Ты всерьёз думаешь твой камент лучше ? Если человек не знаком с рендерингом, ему твой камент ровно ничего не говорит. У твоего кода ровно две неразрешимых проблемы — кишки упрятаны хрен знает куда и каменты имеют свойство устаревать.
В моём случае эти две проблемы решены и код сам говорит о том, соответсвует ли он решению бизнес задачи или нет.
Здравствуйте, Ikemefula, Вы писали:
I>Если ты приходишь на конкретный проект, то приходится осваивать бизнес-специфику. Импорт это всегда перенос готовых из внешнего мира в рассматриваемую систему. Экспорт — это перенос готовых данных из системы во внешний мир. Зачем нужен импорт-экспорт и что такое XXX — это всё в ТЗ и UML. Dыносить это в каменты нет никакой необходимости.
Ты совершенно прав Но актуальные ТЗ и UML — большая редкость. Кроме того, между бизнес-спецификой и конкретным кодом метода часто лежит еще некий промежуточный слой. Для него отдельная документация создается редко. И как минимум базовые классы и интерфейсы, а также их методы стоит комментировать в доксиген стиле. Хотя бы потому, что вероятность устаревания комента ниже, чем отдельной документации
I>По человечески бизнес сущности придется описывать неодним десятком страниц текста. Есть ТЗ, UML и всякие доки, вот там и будет необходимое описание. В коде же вместо I>IterateOverArrayWithDataReceivedOnPreviousStepAndIfYYYHasZZZDoSomeSteps нужно писать SelectUnroutedFacilities.
Ага, и рядом с SelectUnroutedFacilities стоит на разговорном языке описать его
I>>>Несерьёзный пример. Я тебе привел пример из бизнес-задачи, а ты мне сунул битмапы, т.е. к бизнесу никакого отношения E>>А тема разве про комментирование бизнес-задач?
I>Ты пойми простую вещь, битмап и пиксмап известны всем, кто имел дела с рендерингом. Но это не значит, что любой сможет из твоего кода разобраться что такое и для чего нужны битмапы и прочая дрянь. По этой причине в твоём коде рвно тоже что и уменя, за исключением двух неразрешимых проблем.
Дык я ж тебе и объясняю — качественная автосгенеренная дока в конце концов приведет тебя к разжеванным описаниям.
I>Вероятно, тот факт, что декларативный код даёт меньше ошибок, для тебя новость
В теме про комменты сравнение декларативного с функциональным — жуткий офтоп
I>В итоге секундное действие превращается вполчаса перелистывания.
У тебя экран кода. Человек не в теме (или ты сам через год) потратит на его осмысление отнюдь не секунду.
I>Другой пример. Если ты не в курсе конечных автоматов, то тебе без толку декларативное задание конечного автомата. Но твой код со ссылками и каментами ничем не лучше. I>ДЕкларативный код вроде того что я показал, нужен тому, кто знает что такое КА и ему не надо будет мотаться по страницам и вычитывать каменты что бы понять что к чему.
Опять таки перед таблицей с КА хорошо бы написать, что это за КА и зачем он нужен. И всей этой информации место как раз в комменте.
I>Ты всерьёз думаешь твой камент лучше ? Если человек не знаком с рендерингом, ему твой камент ровно ничего не говорит. У твоего кода ровно две неразрешимых проблемы — кишки упрятаны хрен знает куда и каменты имеют свойство устаревать.
Ты забываешь, что часто ТЗ устаревает еще быстрее, чем каменты.
Здравствуйте, enji, Вы писали:
E>Ты совершенно прав Но актуальные ТЗ и UML — большая редкость. Кроме того, между бизнес-спецификой и конкретным кодом метода часто лежит еще некий промежуточный слой. Для него отдельная документация создается редко. И как минимум базовые классы и интерфейсы, а также их методы стоит комментировать в доксиген стиле. Хотя бы потому, что вероятность устаревания комента ниже, чем отдельной документации.
Документация == ТЗ. Если нет ТЗ, то, конечно, туши свет
I>>По человечески бизнес сущности придется описывать неодним десятком страниц текста. Есть ТЗ, UML и всякие доки, вот там и будет необходимое описание. В коде же вместо I>>IterateOverArrayWithDataReceivedOnPreviousStepAndIfYYYHasZZZDoSomeSteps нужно писать SelectUnroutedFacilities.
E>Ага, и рядом с SelectUnroutedFacilities стоит на разговорном языке описать его
Ни в коем разе. В противном случае любую бизнес задачу ты будешь разгребать в пять-десять раз дольше.
I>>Ты пойми простую вещь, битмап и пиксмап известны всем, кто имел дела с рендерингом. Но это не значит, что любой сможет из твоего кода разобраться что такое и для чего нужны битмапы и прочая дрянь. По этой причине в твоём коде рвно тоже что и уменя, за исключением двух неразрешимых проблем.
E>Дык я ж тебе и объясняю — качественная автосгенеренная дока в конце концов приведет тебя к разжеванным описаниям.
Пусть генерится, только на основании той инфы, что отсутствует в рабочем репозитории
I>>В итоге секундное действие превращается вполчаса перелистывания.
E>У тебя экран кода. Человек не в теме (или ты сам через год) потратит на его осмысление отнюдь не секунду.
Если человек не в курсе специфики бизнеса, то это нормально и этого человека никогда не будет в коде. А вот я сам такой код воспринимаю как вчерашний
I>>Другой пример. Если ты не в курсе конечных автоматов, то тебе без толку декларативное задание конечного автомата. Но твой код со ссылками и каментами ничем не лучше. I>>ДЕкларативный код вроде того что я показал, нужен тому, кто знает что такое КА и ему не надо будет мотаться по страницам и вычитывать каменты что бы понять что к чему.
E>Опять таки перед таблицей с КА хорошо бы написать, что это за КА и зачем он нужен. И всей этой информации место как раз в комменте.
Нет смысла затачивать код под тех, кто не в теме.
I>>Ты всерьёз думаешь твой камент лучше ? Если человек не знаком с рендерингом, ему твой камент ровно ничего не говорит. У твоего кода ровно две неразрешимых проблемы — кишки упрятаны хрен знает куда и каменты имеют свойство устаревать. E>Ты забываешь, что часто ТЗ устаревает еще быстрее, чем каменты.
ТЗ постоянно обновляется. Это если эти требования нигде не хранить, а во всяких скайпах, аутлуках, то да. А если требования заносить в UML тот же и кое какие доки, то всё в порядке.
Здравствуйте, Ikemefula, Вы писали:
I>Здравствуйте, enji, Вы писали:
E>>Ты совершенно прав Но актуальные ТЗ и UML — большая редкость. Кроме того, между бизнес-спецификой и конкретным кодом метода часто лежит еще некий промежуточный слой. Для него отдельная документация создается редко. И как минимум базовые классы и интерфейсы, а также их методы стоит комментировать в доксиген стиле. Хотя бы потому, что вероятность устаревания комента ниже, чем отдельной документации.
I>Документация == ТЗ.
Ну смотри — вот есть некое ПО. В нем в частности, есть модули для работы с каким-то внешним оборудованием. Для каждого такого модуля документацией является:
1. Протокол оборудования
2. Описание интерфейса, который должен реализовать модуль
Протокол оборудования обычно не полон. Часть оборудования работает не совсем по протоколу. Есть какие-то тонкости, которые в протоколе не описаны. Наверное, правильно создать отдельное описание всех таких моментов. Но много проще отразить эти места в комментариях прямо в коде.
Наверное, стоит иметь и отдельную доку на интерфейс. Но снова много проще хранить эту доку прямо в тексте в виде доксиген-комментов.
I>Пусть генерится, только на основании той инфы, что отсутствует в рабочем репозитории I>ТЗ постоянно обновляется. Это если эти требования нигде не хранить, а во всяких скайпах, аутлуках, то да. А если требования заносить в UML тот же и кое какие доки, то всё в порядке.
Возможно ты живешь в каком-то лучшем мире, в котором есть детальные актуальные ТЗ , но для меня это из разряда фантастики. А так как затраты на подробное комментирование некоторых ключевых вещей ниже, чем на ведение отдельной доки, то мой выбор — комменты
Здравствуйте, enji, Вы писали:
I>>Документация == ТЗ.
E>Ну смотри — вот есть некое ПО. В нем в частности, есть модули для работы с каким-то внешним оборудованием. Для каждого такого модуля документацией является: E>1. Протокол оборудования E>2. Описание интерфейса, который должен реализовать модуль
E>Протокол оборудования обычно не полон. Часть оборудования работает не совсем по протоколу. Есть какие-то тонкости, которые в протоколе не описаны. Наверное, правильно создать отдельное описание всех таких моментов. Но много проще отразить эти места в комментариях прямо в коде.
Если есть неочевидные тонкости, например расхождения с протоколом, то их и надо коментировать. А выписывать общие вещи вроде твоей битмапины это коту под хвост.
I>>Пусть генерится, только на основании той инфы, что отсутствует в рабочем репозитории I>>ТЗ постоянно обновляется. Это если эти требования нигде не хранить, а во всяких скайпах, аутлуках, то да. А если требования заносить в UML тот же и кое какие доки, то всё в порядке.
E>Возможно ты живешь в каком-то лучшем мире, в котором есть детальные актуальные ТЗ , но для меня это из разряда фантастики. А так как затраты на подробное комментирование некоторых ключевых вещей ниже, чем на ведение отдельной доки, то мой выбор — комменты
Если обсуждается изменение требований, то один из обсуждающих фиксирует это дело в доке. Это что, так сложно ? Эффект от такого подхода очень сложно переоценить.
Здравствуйте, Ikemefula, Вы писали:
I>Если есть неочевидные тонкости, например расхождения с протоколом, то их и надо коментировать. А выписывать общие вещи вроде твоей битмапины это коту под хвост.
Ну дык битмапина — не моя, а из Qt — либы общего назначения. Для либ доки должно быть побольше, чем для пользовательского кода
E>>Возможно ты живешь в каком-то лучшем мире, в котором есть детальные актуальные ТЗ , но для меня это из разряда фантастики. А так как затраты на подробное комментирование некоторых ключевых вещей ниже, чем на ведение отдельной доки, то мой выбор — комменты
I>Если обсуждается изменение требований, то один из обсуждающих фиксирует это дело в доке. Это что, так сложно ? Эффект от такого подхода очень сложно переоценить.
ТЗ обычно есть только общее — что должно делать ПО с точки зрения заказчика. Частностей вроде описания каких-то внутренних интерфейсов там нет. И вот эти внутренние интерфейсы как раз и документируются в каментах.
Смотри, ты утверждаешь выше :
EOH>Что здесь нечитаемого? I>Всё ! Код в 20-30 строчек превращается в 5-10 страниц и секундное дело превращается в получасовое листание страниц туда-обратно. EOH>Я предпочитаю сразу все коментировать в нотаци, совместимой с извлекалками докуентаций. Хорошо время экономит. I>Коментить лучше в отдельном репозитории для контрактов. комменты автоматически мерджатся с контрактами из рабочих бранчей и код не засоряется всяким говном.
Я не считаю, что комментировать надо построчно. Но, имхо, интерфейсы и базовые классы должны быть задокументированы. И проще всего это сделать в каментах. Если описание интерфейса займет 5 страниц вместо 1-й — ну и что? ИДЕ умеют сворачить комменты.
Документация же в отдельном репозитории устареет просто влет, если нет специальной процедуры ее обновления. Кроме того, ИДЕ умеет показывать инфу из комментов при автодополнении. Как с этим у стороннего репозитория? наверное настроить его можно, но вот зачем? Чтобы интерфейс занимал меньше места в файле?
Здравствуйте, Eye of Hell, Вы писали:
BBI>>Скопипастить сюда понятное дело не могу. BBI>>А так: комменты ровно там, где они нужны. Для пояснения зачем и почему. EOH>Насколько з знаю, системы автоматической генерации документации обычно используются для публичных API. С вашей точки зрения — публичные API это "ровно то место" где комменты нужны или "не ровно"?
Winapi — публичный API?
И тем не менее самая лучшая документация по нему — старый MSDN.
Именно так должен описываться публичный API, а не в вариациях doxygen style
Здравствуйте, Banned by IT, Вы писали:
BBI>Здравствуйте, Eye of Hell, Вы писали:
BBI>>>Скопипастить сюда понятное дело не могу. BBI>>>А так: комменты ровно там, где они нужны. Для пояснения зачем и почему. EOH>>Насколько з знаю, системы автоматической генерации документации обычно используются для публичных API. С вашей точки зрения — публичные API это "ровно то место" где комменты нужны или "не ровно"?
BBI>Winapi — публичный API? BBI>И тем не менее самая лучшая документация по нему — старый MSDN. BBI>Именно так должен описываться публичный API, а не в вариациях doxygen style
Мне программировать на Java, чем на С++ не в пример приятнее в том числе из за того, что там все функции документированы жавадоками и расстояние от IDE до описания функции — полсекунды наведения курсора на её вызов (или нажатия F2). В случае с MSDN-ом всё намного дольше и неинтегрированней.
Здравствуйте, enji, Вы писали:
I>>Если обсуждается изменение требований, то один из обсуждающих фиксирует это дело в доке. Это что, так сложно ? Эффект от такого подхода очень сложно переоценить.
E>ТЗ обычно есть только общее — что должно делать ПО с точки зрения заказчика. Частностей вроде описания каких-то внутренних интерфейсов там нет. И вот эти внутренние интерфейсы как раз и документируются в каментах.
За счет ухудшения читабельности кода. Ты пойми, каменты не избавляют тебя от необходимости прочесть код.
E>Документация же в отдельном репозитории устареет просто влет, если нет специальной процедуры ее обновления. Кроме того, ИДЕ умеет показывать инфу из комментов при автодополнении. Как с этим у стороннего репозитория? наверное настроить его можно, но вот зачем? Чтобы интерфейс занимал меньше места в файле?
Проще простого сделать утилиту которая будет подсказывать, какие каменты надо обновить. А для редактирование каментов надо включать в процесс. Итого — отдельная репа для каментов дает тебе доп. точку контроля.
Здравствуйте, Ikemefula, Вы писали:
E>>ТЗ обычно есть только общее — что должно делать ПО с точки зрения заказчика. Частностей вроде описания каких-то внутренних интерфейсов там нет. И вот эти внутренние интерфейсы как раз и документируются в каментах.
I>За счет ухудшения читабельности кода.
ИМХО, это какая-то надуманная проблема. ИДЕ умеет делать автосвертку, включи ее и ты даже не заметишь комментов.
I>Ты пойми, каменты не избавляют тебя от необходимости прочесть код.
Ну конечно не избавит. Зато поможет даст информацию, которую в противном случае придется долго и мучительно восстанавливать из кода. А иногда ее просто невозможно восстановить из кода
E>>Документация же в отдельном репозитории устареет просто влет, если нет специальной процедуры ее обновления. Кроме того, ИДЕ умеет показывать инфу из комментов при автодополнении. Как с этим у стороннего репозитория? наверное настроить его можно, но вот зачем? Чтобы интерфейс занимал меньше места в файле?
I>Проще простого сделать утилиту которая будет подсказывать, какие каменты надо обновить. I>А для редактирование каментов надо включать в процесс. Итого — отдельная репа для каментов дает тебе доп. точку контроля.
Ага, и дополнительный геморрой по настройке всего этого добра. Плюс к этому, основное преимущество комментов перед отдельной докой — их проще поддерживать актуальными. Вынеси комменты в отдельное место — все теряется.
Т.е. вместо обычного редактора из ИДЕ нужна еще отдельная утилита. Нужен отдельный репозиторий, из которого надо файлы с комментами доставать и не забывать их там обновлять. Все значительно усложняется, и ради чего? Чтобы можно было не поставить в ИДЕ галку "сворачивать комменты"? Цель какая-то мелкая, по сравнению со средствами для ее достижения
Здравствуйте, enji, Вы писали:
I>>За счет ухудшения читабельности кода.
E>ИМХО, это какая-то надуманная проблема. ИДЕ умеет делать автосвертку, включи ее и ты даже не заметишь комментов.
Некоторые комменты нужны, некоторые — нет. Большая часть каментов не нужна в принципе.
I>>Ты пойми, каменты не избавляют тебя от необходимости прочесть код. E>Ну конечно не избавит. Зато поможет даст информацию, которую в противном случае придется долго и мучительно восстанавливать из кода. А иногда ее просто невозможно восстановить из кода
Каменты, грубо говря, удваивают затраты на майнтенанс кода. Поменял ты бехеверир — обнови каменты. Если этого нет, каменты тоьлко запутывают.
I>>А для редактирование каментов надо включать в процесс. Итого — отдельная репа для каментов дает тебе доп. точку контроля. E>Ага, и дополнительный геморрой по настройке всего этого добра. Плюс к этому, основное преимущество комментов перед отдельной докой — их проще поддерживать актуальными. Вынеси комменты в отдельное место — все теряется.
Не проще. Поговорил ты скажем по скайпу с кастомером — обнови вики-страничку с требованиями. Весь код может будет готов только через месяц. А где ты инфу до этого будешь хранить ?
Соответсвенно, инфу надо хранить уже до того, как появится место для каментов. Стало быть каменты будут просто дублировать да еще требовать время на майнтенанс.
E>Т.е. вместо обычного редактора из ИДЕ нужна еще отдельная утилита. Нужен отдельный репозиторий, из которого надо файлы с комментами доставать и не забывать их там обновлять. Все значительно усложняется, и ради чего? Чтобы можно было не поставить в ИДЕ галку "сворачивать комменты"? Цель какая-то мелкая, по сравнению со средствами для ее достижения
Идея в том, что 1 требования нужно отделить от кода 2 каменты можно мерджить с кодом, в этом случае получится нечто вроде annotate только будет добавлять еще и каменты.
Здравствуйте, Banned by IT, Вы писали:
EOH>>Что здесь нечитаемого? BBI>Всё. BBI>За деревьями не видно кода.
В таком случае регионы решают. Вообще в последнее время я их полюбил очень сильно. Времени отнимают гораздо меньше на написание и поддержку, а зачастую могут исключить необходимость писать классические комментарии. Так же помогают отделить служебный код от логики и т.д. в тех местах где разделение такого кода по методам было бы полнейшим оверхедом (например парсинг аргументов и т.п.). Говорю по собственному опыту, т.к. недавно пришел в команду, практикующую именно такой подход и код реально читался "с листа".
Здравствуйте, Ikemefula, Вы писали:
I>Большая часть каментов не нужна в принципе.
Хз, зависит от того, как их писать
I>Каменты, грубо говря, удваивают затраты на майнтенанс кода. Поменял ты бехеверир — обнови каменты. Если этого нет, каменты тоьлко запутывают.
Если я поменял интерфейс, то мне всяко надо где-то написать, как именно он теперь работает. Иначе могут быть сюрпризы у того, кто меня использует. Если же я поменял детали реализации — то комменты надо обновлять только если они были. А были они, если реализация нетривиальная. Дык если реализация нетривиальная и не имеет комментов, то затраты на изменение поведения вырастут в разы
I>>>А для редактирование каментов надо включать в процесс. Итого — отдельная репа для каментов дает тебе доп. точку контроля. E>>Ага, и дополнительный геморрой по настройке всего этого добра. Плюс к этому, основное преимущество комментов перед отдельной докой — их проще поддерживать актуальными. Вынеси комменты в отдельное место — все теряется.
I>Не проще. Поговорил ты скажем по скайпу с кастомером — обнови вики-страничку с требованиями. Весь код может будет готов только через месяц. А где ты инфу до этого будешь хранить ? I>Соответсвенно, инфу надо хранить уже до того, как появится место для каментов. Стало быть каменты будут просто дублировать да еще требовать время на майнтенанс.
Дык я ж писал уже выше — разговоры с кастомером = "высокоуровневые" требования — что и как должно делать приложение. Это никак не заменяет комментов к интерфейсам или базовым классам. В разговорах с кастомерм они вообще не фигурируют
I>2 каменты можно мерджить с кодом, в этом случае получится нечто вроде annotate только будет добавлять еще и каменты.
Вот эта идея мне не нравится. Точнее она возможно и неплоха, но требует инструментов, которые конкретно у меня отсутствуют. Более того, я вообще их не видел вживую. Когда такие инструменты появятся и можно будет пощупать, как это все работает — то почему бы и нет.
Прямо счас комменты в коде не доставляют мне никаких проблем, поэтому нет никакого желания писать\искать инструменты для их раздельного хранения
Здравствуйте, enji, Вы писали:
I>>Большая часть каментов не нужна в принципе. E>Хз, зависит от того, как их писать
Зависит от того, как ты _код_ пишешь Если умеешь писать код, каментов приходится писать где то на порядок меньше.
I>>Каменты, грубо говря, удваивают затраты на майнтенанс кода. Поменял ты бехеверир — обнови каменты. Если этого нет, каменты тоьлко запутывают. E>Если я поменял интерфейс, то мне всяко надо где-то написать, как именно он теперь работает.
Зачем ?
>Иначе могут быть сюрпризы у того, кто меня использует. Если же я поменял детали реализации — то комменты надо обновлять только если они были. А были они, если реализация нетривиальная. Дык если реализация нетривиальная и не имеет комментов, то затраты на изменение поведения вырастут в разы
Даже если есть каменты, это не избавляет от необходимости лезть в код.
I>>Не проще. Поговорил ты скажем по скайпу с кастомером — обнови вики-страничку с требованиями. Весь код может будет готов только через месяц. А где ты инфу до этого будешь хранить ? I>>Соответсвенно, инфу надо хранить уже до того, как появится место для каментов. Стало быть каменты будут просто дублировать да еще требовать время на майнтенанс. E>Дык я ж писал уже выше — разговоры с кастомером = "высокоуровневые" требования — что и как должно делать приложение. Это никак не заменяет комментов к интерфейсам или базовым классам. В разговорах с кастомерм они вообще не фигурируют
Если не фигурируют, то по барабану — т.к. кастомера АПИ не интересует.
Здравствуйте, Ikemefula, Вы писали:
I>>>Каменты, грубо говря, удваивают затраты на майнтенанс кода. Поменял ты бехеверир — обнови каменты. Если этого нет, каменты тоьлко запутывают. E>>Если я поменял интерфейс, то мне всяко надо где-то написать, как именно он теперь работает.
I>Зачем ?
Потому что АПИ состоит из двух частей — сигнатуры и семантики. Сигнатуры проверяет компилятор, а вот семантика (неочевидная из имен методов) как раз и описывается в комментариях.
>>Иначе могут быть сюрпризы у того, кто меня использует. Если же я поменял детали реализации — то комменты надо обновлять только если они были. А были они, если реализация нетривиальная. Дык если реализация нетривиальная и не имеет комментов, то затраты на изменение поведения вырастут в разы
I>Даже если есть каменты, это не избавляет от необходимости лезть в код.
Ты пошел по второму кругу Мое мнение с тех пор не поменялось — наличие комментов сильно упрощает понимание кода.
I>>>Не проще. Поговорил ты скажем по скайпу с кастомером — обнови вики-страничку с требованиями. Весь код может будет готов только через месяц. А где ты инфу до этого будешь хранить ? I>>>Соответсвенно, инфу надо хранить уже до того, как появится место для каментов. Стало быть каменты будут просто дублировать да еще требовать время на майнтенанс. E>>Дык я ж писал уже выше — разговоры с кастомером = "высокоуровневые" требования — что и как должно делать приложение. Это никак не заменяет комментов к интерфейсам или базовым классам. В разговорах с кастомерм они вообще не фигурируют
I>Если не фигурируют, то по барабану — т.к. кастомера АПИ не интересует.
Ну и я про то же самое — кастомера интересуют возможности программы, которые описываются в ТЗ. А вот АПИ описывается в комментах. Потому что городить отдельную докуменацию на АПИ обычно перебор.
Здравствуйте, enji, Вы писали:
I>>Зачем ?
E>Потому что АПИ состоит из двух частей — сигнатуры и семантики. Сигнатуры проверяет компилятор, а вот семантика (неочевидная из имен методов) как раз и описывается в комментариях.
Семантику как раз и надо описывать кодом таким образом, что бы было из имен полей, методов, классов и итд было очевидно
Хочешь не хочешь, но каменты не дают такой информации как код.
I>>Даже если есть каменты, это не избавляет от необходимости лезть в код. E>Ты пошел по второму кругу Мое мнение с тех пор не поменялось — наличие комментов сильно упрощает понимание кода.
А ты что, решил что я стараюсь поменять твоё мнение ?
I>>Если не фигурируют, то по барабану — т.к. кастомера АПИ не интересует. E>Ну и я про то же самое — кастомера интересуют возможности программы, которые описываются в ТЗ. А вот АПИ описывается в комментах. Потому что городить отдельную докуменацию на АПИ обычно перебор.
Перебор это приседать с документированием АПИ если это не требуется кастомеру.
Даже самые распрекрасные каменты не избавят необходимости читать код. А вот правильно написаный код заменяет каменты, кроме случаев, когда кастомеру нужен документированый АПИ или неочевидные вещи, про которые был пример.
Здравствуйте, Ikemefula, Вы писали:
I>>>Зачем ?
E>>Потому что АПИ состоит из двух частей — сигнатуры и семантики. Сигнатуры проверяет компилятор, а вот семантика (неочевидная из имен методов) как раз и описывается в комментариях.
I>Семантику как раз и надо описывать кодом таким образом, что бы было из имен полей, методов, классов и итд было очевидно
Ну и как ты этого добьещься? Ты приводил пример своего кода, из него семантика не очевидна никому, кроме тех, кто в теме. Я вот год назад написал
Через год я уже забыл что это такое и зачем оно нужно. Однако год назад я добавил пару комментов. Они помогли быстрее восстановить назначение этого класса
I>Хочешь не хочешь, но каменты не дают такой информации как код.
Конечно не дают. Они дают _другую_ информацию — в этом и есть их назначение. Комменты, дублирующие код не нужны...
I>>>Даже если есть каменты, это не избавляет от необходимости лезть в код. E>>Ты пошел по второму кругу Мое мнение с тех пор не поменялось — наличие комментов сильно упрощает понимание кода.
I>А ты что, решил что я стараюсь поменять твоё мнение ?
А зачем тогда повторяешься?
I>>>Если не фигурируют, то по барабану — т.к. кастомера АПИ не интересует. E>>Ну и я про то же самое — кастомера интересуют возможности программы, которые описываются в ТЗ. А вот АПИ описывается в комментах. Потому что городить отдельную докуменацию на АПИ обычно перебор.
I>Перебор это приседать с документированием АПИ если это не требуется кастомеру.
Это требуется мне, чтобы через год-два-три при необходимости что-то поменять быстро вникнуть в АПИ
Здравствуйте, enji, Вы писали:
I>>Семантику как раз и надо описывать кодом таким образом, что бы было из имен полей, методов, классов и итд было очевидно
E>Ну и как ты этого добьещься? Ты приводил пример своего кода, из него семантика не очевидна никому, кроме тех, кто в теме.
Естественно. Вариантов два — код понятен только автору на момент написания и код понятен только тем, кто в теме. Делай свой выбор
E>Через год я уже забыл что это такое и зачем оно нужно. Однако год назад я добавил пару комментов. Они помогли быстрее восстановить назначение этого класса
Могу только посочувствовать. Имена вроде *Wrapper,*Helper и тд обычно мусор и не отражают реального положения дел. Для чего тебе нужен был этот враппер ?
I>>Хочешь не хочешь, но каменты не дают такой информации как код. E>Конечно не дают. Они дают _другую_ информацию — в этом и есть их назначение. Комменты, дублирующие код не нужны...
ну так ты же и предложил описывать бехевиор в каментах, а я тебе и говорю, что такие каменты дублируют код.
I>>Перебор это приседать с документированием АПИ если это не требуется кастомеру. E>Это требуется мне, чтобы через год-два-три при необходимости что-то поменять быстро вникнуть в АПИ
Тогда лучше потратиться на качественные названия. Каменты тебя не спасут.
. Приходится наворачивать над ними свои альясы как показано выше.
