Здравствуйте, Banned by IT, Вы писали:

BBI>К тому, что очень уж это геморно получится.
BBI>Человек человека порой может неправильно понять, не говоря уже про компилятор.

http://rsdn.ru/forum/philosophy/4422415.1.aspx

Автор: Ikemefula
Дата: 15.09.11

Что тебе непонятно ?

Здравствуйте, Banned by IT, Вы писали:

BBI>Человек человека порой может неправильно понять, не говоря уже про компилятор.

Компилятор получает на вход программу. Что он там может понять неправильно??? Человек видит статью, которая описывает то, как работает программа. Тут же рядом исходник. Какие могут быть проблемы???

Все в итоге выглядит примерно так: gsearch.

EOH>>Вы можете привести пример кода с комментариями не предназначенными для системы автоматической генерации докумнтации который вы оцениваете как читаемый?

I>Конечно. Смотри пример, декларативный код и комент только там где нет возможности выразить intention самим же кодом.

Насколько я понимаю топикстартера, вопрос не а том "писать комменты или писать самодокументированный код" а "писать комменты для системы автогенерации документации или писать комменты не для системы автогенерации документации". Или я не прав?

BTW, приведенный вами пример — это внутренности программы. Комментарии обычно массово пишут для торчащего наружу API / точек взаимодействий модулей.

Здравствуйте, Ikemefula, Вы писали:

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

Очень интересный подход. Я даже о таком не думал.

Здравствуйте, Eye of Hell, Вы писали:

BBI>>Комменты для системы автоматического докуменирования практически всегда засирают код
EOH>Попробую еще раз — а можете привести пример комментов не для системы автомаического документирования, которые, по вашему мнению, код не засирают?
Скопипастить сюда понятное дело не могу.
А так: комменты ровно там, где они нужны. Для пояснения зачем и почему.

Здравствуйте, Eye of Hell,

ГМ>>Третий минус в том, что код и комментарии к нему могут потерять "синхронизацию".
ГМ>>Например, при изменении кода комментарии не изменились.

EOH>Соответствено чем ближе комментарии к коду, тем меньше шанс на рассинхронизацию?
--
Нет, не так.
IMHO, между расстоянием код/комментарий и шансом на рассинхронизацию особой связи нет.

C уважением,
Геннадий Майко.

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>Сравни

Несерьёзный пример. Я тебе привел пример из бизнес-задачи, а ты мне сунул битмапы, т.е. к бизнесу никакого отношения

И я бы выкинул каменты и оставил нечто вроде:

public static Bitmap From(this Pixmap pixmap)
{
    return ExactCopy(pixmap).Into<Bitmap>().When(px => px.Depth > 1).Dither();
}

Но очевидно, в низкоуровневом программировании это съест перформанс и только это может быть оправданием твоим каментам.

Кроме того, человек, который не работал с рендерингом, и ничего не знает про 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>public static Bitmap From(this Pixmap pixmap)
I>{
I>    return ExactCopy(pixmap).Into<Bitmap>().When(px => px.Depth > 1).Dither();
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>>public static Bitmap From(this Pixmap pixmap)
I>>{
I>>    return ExactCopy(pixmap).Into<Bitmap>().When(px => px.Depth > 1).Dither();
I>>}
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>Документация же в отдельном репозитории устареет просто влет, если нет специальной процедуры ее обновления. Кроме того, ИДЕ умеет показывать инфу из комментов при автодополнении. Как с этим у стороннего репозитория? наверное настроить его можно, но вот зачем? Чтобы интерфейс занимал меньше места в файле?

Проще простого сделать утилиту которая будет подсказывать, какие каменты надо обновить. А для редактирование каментов надо включать в процесс. Итого — отдельная репа для каментов дает тебе доп. точку контроля.