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

B>А это надо описывать не комментариями, а в отдельных дизайн-документах.
Отдельные дизайн-документы имеют привычку совершенно не соответствовать коду для которого написаны. И поддерживать это дело в согласованном состоянии — лишняя трата сил.

B>Ты же не будешь рассчитывать, что другие будут лезть в исходники,
B>чтобы понять как этим добром пользоваться.
Рассчитываю.

B>Для этих целей надо писать специальный док, посвященный жтому аспекту.
В доке описывается общий концепт и предназначение, а особенности конкретной реализации только в коде.

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

AVK>>Сразу писать, потому что иначе это начинает смахивать на профанацию.
WH>Сразу это когда?

Сразу, Андрей Михалыч, сразу как пишешь публичные интерфейсы.

WH> Например я пишу их перед комитом.

Я помню.

WH> Раньше просто нет смысла ибо у меня методы в процессе кодирования постоянно появляются и исчезают или меняется их функциональность.

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

WH> К тому же для написания комментариев нужно переключить мозги на другой режим работы,

Не нужно. А если приходится переключать, то значит это не комментарии, а мухлеж.

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

M>Ага. Только отдельного документа описывающего архитектуру это ни в коем случае не отменяет. javadoc позволяет описать интерфейсы классов, а не то как они используются, для чего нужны или почему они спроектированны именно так. Стоит отметить, что комментарии в коде на эти вопросы обычно не отвечают. Поэтому, кстати, документацией на явовские классы, даже официальной, пользоваться менее удобно чем MSDN.

А ты чего думаешь, референс для .NET Framework не автоматом генерится?

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

GZ>Тут лучше сделать сразу две задачи.
GZ>1. Задокументировать с помощью Unit-тестов и(или) examples.(чаще полезней чем различные списки интерфейсов)

examples -- это must have. Но кроме больших примеров, должны быть еще и маленькие. Которые хорошо бы давать в документации к методу/классу.

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

К тому же в Unit-тесте элементарно много синтаксического мусора. Всякие assert_nothing_raised или BOOST_CHECK_EQUAL. Да и комментарии могу быть не очень осмысленными. Вроде такого "Проверка bug-report #45736" и URL на внутренний bug-tracking.

GZ>2. Задокументировать библиотеку, как — уже неважно. К вопросам комментариев мало относится. Как ты документируешь с помощью комментариев или просто вручную написав документ, твое личное дело. И к тому же оно совершенно не касается внутреннего кода.

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

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

AVK>А ты чего думаешь, референс для .NET Framework не автоматом генерится?

Я не думая, я знаю что генерится. Только в MSDN кроме него еще статьи об общей архитектуре модуля и примеры имеются. А одинм референсом жив не будешь.

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

AVK>>А ты чего думаешь, референс для .NET Framework не автоматом генерится?

M>Я не думая, я знаю что генерится. Только в MSDN кроме него еще статьи об общей архитектуре модуля и примеры имеются. А одинм референсом жив не будешь.

Ну это само собой. Только статьи там обзорного плана, а не описание кода библиотеки. Какое ониимеют отношение к комминтированию кода?

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

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

B>>А это надо описывать не комментариями, а в отдельных дизайн-документах.
M>Отдельные дизайн-документы имеют привычку совершенно не соответствовать коду для которого написаны. И поддерживать это дело в согласованном состоянии — лишняя трата сил.

С комментариями такая же проблема.

На проекте очень много чего надо держать в согласованном состоянии.
Начиная от желаний с возможностями (план, требования, бюджет и ресурсы),
заканчивая комментариями которые должны описывать то, что реально есть.

B>>Ты же не будешь рассчитывать, что другие будут лезть в исходники,
B>>чтобы понять как этим добром пользоваться.
M>Рассчитываю.

Хм... А я вот предпочитаю в потроха вообще без надобности не лезть.
Ну если баг или документация плохая, тогда да, придется залезть в исходники.

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

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

AVK>>>А ты чего думаешь, референс для .NET Framework не автоматом генерится?

M>>Я не думая, я знаю что генерится. Только в MSDN кроме него еще статьи об общей архитектуре модуля и примеры имеются. А одинм референсом жив не будешь.

AVK>Ну это само собой. Только статьи там обзорного плана, а не описание кода библиотеки. Какое ониимеют отношение к комминтированию кода?

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

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

M>Самое прямое, особенно если речь идет о библиотеке. Они облегчают понимание архитектуры и помогают при использовании этого кода. А для чего еще по твоему нужны комментарии?

Комментарии нужны для того чтобы комментировать код. Статьи из MSDN код не комментируют, это скорее tutorial.

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

B>С комментариями такая же проблема.
Да, но их легче поддерживать в согласованном состоянии, так как все в одном месте лежит.

>Хм... А я вот предпочитаю в потроха вообще без надобности не лезть.
Код — это лучшая документация, все остальное вторично. Так что если надо действительно разобраться, то без кода все равно никуда...

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

AVK>Комментарии нужны для того чтобы комментировать код. Статьи из MSDN код не комментируют, это скорее tutorial.
То что ты говоришь, это тавтология. "Веревка, суть, вервие простое".
Задам вопрос иначе: Для чего нужно комментировать код? Что это дает? Чем "комментированный" код лучше "некомментированного"?

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

M>Задам вопрос иначе: Для чего нужно комментировать код? Что это дает? Чем "комментированный" код лучше "некомментированного"?

Тем что комментированный проще читать и рефакторить.

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

>>Хм... А я вот предпочитаю в потроха вообще без надобности не лезть.
M>Код — это лучшая документация, все остальное вторично. Так что если надо действительно разобраться, то без кода все равно никуда...

Спорно, спорно...
Черный ящик — штука хорошая.
Действительно разбираться надо только если ты это собираешься менять и поддерживать.
Т.е. это становится куском за, который ты лично отвечаешь.
А если я этим куском пользуюсь, то мне потроха не нужны, до тех пор, пока это работает.

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

E>Есть одина область разработки ПО, где такой подход не применим вообще -- разработка библиотек.

Библиотека — это бинарник, комментарии в его исходниках пользователю не видны. На библиотеку надо писать отдельный документ — руководство по использованию.

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

M>Сразу — это перед написанием метода.
Это очень зависит от того человека. В моем случае это не реально.

M>Тут идея в том, что если ты сосредоточишься на том чтобы написать комментарий, то ты четко поймешь для чего на самом деле тебе этот метода нужен, и тебе не придется его десять раз переписывать.
Это если ты все спроектировал ДО написания кода. Я так не умею. Я проектирую подсисетму во время написания кода. Благо ReSharper сводит оверхед от нерпирывного рефакторинга к нулю.
Проектировать во время написания кода мне приходится по тому что тот вид в котором представлена программа в моей голове не имеет ничего общего с кодом программы, а думать в терминах кода слишком трудно я все-таки на машина...
Во время написания кода я превращаю одно представление в другое причем превращение неоднозначное (по этому приходится перебирать различные варианты кода -> рефакторинг...) и с потерями (а как еще можно свернуть многомерное (я даже затрудняюсь сказать в скольки измерениях работает моя голова и вобще можно ли это назвать измерениями... вобще саморефлексия довольно не простое занятие) представление в направленный граф с иерархией?). Причем во время кодирования я налету превращаю то что написал в свое внутренние представление и сравниваю то что получилось с базовой моделью. А самое противное что довольно часто выясняется что то что придумал не возможно или очень трудно выразить в коде. По этому приходится рефакторить базовую модель что часто ведет к рефакторингу уже написанного кода.
Вобщем если ты можешь писать комментарии до написания кода то пиши. Я так не могу.

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

M>>Задам вопрос иначе: Для чего нужно комментировать код? Что это дает? Чем "комментированный" код лучше "некомментированного"?
AVK>Тем что комментированный проще читать и рефакторить.
Лично я предпочитаю не комментированный код, а обзорную статью о том что к чему. Ибо в моем случае просто читать код бесполезсно. Я должен превратить его в свое внутреннее представление.
Так вот комментарии типа:

    /// <summary>
    /// Линк в дереве
    /// </summary>
    public class TreeLink
    {
        private string _linkName = string.Empty;
        private string _linkUrl = string.Empty;

        /// <summary>
        /// Инициализирует экземпляр
        /// </summary>
        public TreeLink()
        {
        }

        /// <summary>
        /// Инициализирует экземпляр переданными параметрами
        /// </summary>
        /// <param name="name"></param>
        /// <param name="url"></param>
        public TreeLink(string name, string url)
        {
            _linkName = name;
            _linkUrl = url;
        }

        /// <summary>
        /// Имя линка
        /// </summary>
        [JanusDisplayName("TreeLinkConfigNameName")]
        [JanusDescription("TreeLinkConfigNameDescription")]
        [JanusCategory("CategoryNameTreeLinkCommon")]
        public string LinkName
        {
            get { return _linkName; }
            set { _linkName = value; }
        }

        /// <summary>
        /// Значение линка
        /// </summary>
        [JanusDisplayName("TreeLinkConfigLinkName")]
        [JanusDescription("TreeLinkConfigLinkDescription")]
        [JanusCategory("CategoryNameTreeLinkCommon")]
        public string LinkUrl
        {
            get { return _linkUrl; }
            set { _linkUrl = value; }
        }

Не дают мне никакой дополнительной информации. Только отвлекают.
А вот еслибы была небольшая статья о том что к чему то из этой статьи я смог бы востановить скелет подсисетмы. Имея представление о скелете подсистемы даже если это представление не точное и не полное востановление логики из кода будет происходить немного проще и быстрее.

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

WH>Это если ты все спроектировал ДО написания кода. Я так не умею. Я проектирую подсисетму во время написания кода. Благо ReSharper сводит оверхед от нерпирывного рефакторинга к нулю.
WH>Проектировать во время написания кода мне приходится по тому что тот вид в котором представлена программа в моей голове не имеет ничего общего с кодом программы, а думать в терминах кода слишком трудно я все-таки на машина...

Не в пику тебе, а вспоминая тему Проектирование и рефакторинг

Автор: VladD2
Дата: 09.02.06

. После проектирования на бумаге при вводе кода в редакторе комментарии перед написанием кода писать не сложно. Если только лень не одолевает.

Здравствуйте, Сергей Губанов, Вы писали:

E>>Есть одина область разработки ПО, где такой подход не применим вообще -- разработка библиотек.

СГ>Библиотека — это бинарник, комментарии в его исходниках пользователю не видны. На библиотеку надо писать отдельный документ — руководство по использованию.

Сергей, твои проявления детской непосредственности временами приводят меня в полный восторг. Почитай мои сообщения в данной ветке и ты увидишь, что я писал про два типа документов, необходимые для библиотеки: tutorial и reference manual. У этих документов разные задачи. Из tutorial-а ты должен понять, к примеру, что есть такой mixin Enumerable, которы добавляет к классам замечательную функциональность. Что класс Array подмешивает к себе этот mixin. Что Enumerable содержит методы each и each_with_index. Что если у объекта есть метод each, то можно использовать этот объект в цикле for. Следовательно, сделать итерацию по Array в цикле for возможно потому, что метод each в него подмешивается через Enumerable.

Это все задача tutorial-а. Сюда же входит и написание понятных и выразительных примеров. Совсем не обязательно писать tutorial в исходниках в специализированных комментариях. Хотя современные инструменты генерации документации (JavaDoc, Doxygen, RDoc) позволяют это делать. И это даже удобно: примеры автоматически индексируются и в них вставляются гиперссылки на reference manual.

А вот у reference manual совсем другая задача. Reference manual предназначен для поиска детальной информации о конкретном модуле/классе/функции. Например, ты помнишь, что у Array есть какой-то метод, который позволяет идти по элементам и их индексам. И содержит этот метод в названии index. Не искать же это описание в tutorial. Вместо этого ты берешь reference manual и находишь список методов класса Array и видишь там среди прочего метод each_with_index. После этого ты сразу можешь посмотреть его формат и коротенький пример использования.

Так вот речь шла о том, что практика показала удобство создания reference manual прямо в исходных текстах посредством специальных комментариев и специальных программ (JavaDoc и К). То, во что конкретно превращается reference manual (HTML, CHM, PS, PDF) и во что превращается библиотека (LIB, DLL, JAR, GEM) при публикации -- это уже другой вопрос и он не имеет отношения к теме разговора. Важно, что исходное содержимое reference manual находится в непосредственной близости от описываемого им кода.

---

Ну и напоследок. Есть замечательные языки, у которых библиотеки -- это не бинарники, а исходники

_>>Для этих целей лучше использовать какую-нибудь систему типа doxygen.
_>>Видел как java-api документация описана? Прям в исходниках!
M>Ага. Только отдельного документа описывающего архитектуру это ни в коем случае не отменяет. javadoc позволяет описать интерфейсы классов, а не то как они используются, для чего нужны или почему они спроектированны именно так. Стоит отметить, что комментарии в коде на эти вопросы обычно не отвечают. Поэтому, кстати, документацией на явовские классы, даже официальной, пользоваться менее удобно чем MSDN.

Doc-O-Matic в этом плане нехило помогает. Он, правда, стоит, зараза....