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

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 находится в непосредственной близости от описываемого им кода.

---

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

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

Не комментирую вообще, или только по просьбе. Если код непонятный, то комментарии не особо помогают(там чаще такую фигню пишут, лишь бы просто написать). Ежели код понятный, то смысла нет. Какой нибудь отдельный документ описывающий общую архитектуру и как это работает больше помогает для разбора, чем комментарии. Но все это мое IMHO.

С уважением, Gleb

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

Сразу писать, потому что иначе это начинает смахивать на профанацию.

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

А>Добрый день.

А>... Поэтому возникает вопрос на каком этапе их писать? ...
А>Вот и хочется услышать соображения на этот счет. Поделитесь опытом.

Непосредственно перед написанием кода.
Очень способствует написанию кода, который делает именно то, что нужно, а не то, что сделать проще/удобнее.

Проверено на кошках.

Здравствуйте, 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. Так вот справочник писать после написания библиотеки, имхо, совершенно гиблое дело. И лучше, если такой справочник строится из исходников, а документация в исходниках (в виде комментариев) пишется сразу при написании кода.

Вообще конечно я с этом согласен в идеале. Но на практике порой бывает, что не совсем понятно, что писать. Например:
1. Требования заданы не четко, да еще и меняються постоянно. Мол сделай так, чтобы работало быстро и надежно, а как придумай сам.
2. Не отлажен процесс проектирования, пишешь кусок кода — показываешь. Конечно с этим надо бороться, но не так все просто, особенно когда патология укоренилась.
3. На этапе кодирования понимаешь, что чего-то не учел или что то, что задумано будет работать совсем не так как задумано (даже где-то в РУПе слышал такой термин, "перекрестное проектирование" так что ли, когда одновременно проектируют и кодируют). В итоге переписываешь кусок кода, меняется логика и комментарии пишешь заново.

Должен же быть какой-то компромис.

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

M>>Непосредственно перед написанием кода.
M>>Очень способствует написанию кода, который делает именно то, что нужно, а не то, что сделать проще/удобнее.

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

B>Комментарии же бывают разные.
B>Интерфейсную часть комментирую сразу.
B>А детали реализации ближе к концу, если это вообще надо.
B>Бывает что комментарии просто не нужны, потому что все видно из самого кода.

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

Я комментарии почти не делаю, потому что знаю, что они очень быстро рассогласовываются с кодом, к которому они относятся и снижают понятность.
Стараюсь писать self-documenting code, то есть выбираю такие названия для методов переменных и пр. объектов, чтобы из названий было понятно, что это. Например, я никогда не пишу timeout, а всегда timeoutInSeconds или timeoutInMinutes.
Теперь, когда в MSVS 2005 есть рефакторинг, нормальные названия стало давать значительно проще.
Таков мой подход.

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

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

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

GZ>Не комментирую вообще, или только по просьбе. Если код непонятный, то комментарии не особо помогают(там чаще такую фигню пишут, лишь бы просто написать). Ежели код понятный, то смысла нет. Какой нибудь отдельный документ описывающий общую архитектуру и как это работает больше помогает для разбора, чем комментарии. Но все это мое IMHO.

Есть одина область разработки ПО, где такой подход не применим вообще -- разработка библиотек. Написание документации по библиотеки, которую будут использовать разные программисты с разными тараканами в голове -- это очень неблагодарное дело. Но хуже всего, что для библиотеки нужен Reference Manual про ее API. Самый удобный способ получения такого manual-а -- это написание специальных комментариев в коде которые затем обрабатываются специализированным инструментом (JavaDoc, Doxygen, RDoc, DDoc и пр.). Если при разработке библиотки комментарии не писать сразу, то задокументировать ее затем будет весьма трудоемким и, возможно, бесполезным занятием.

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


А>Вот и хочется услышать соображения на этот счет. Поделитесь опытом.

Я стараюсь писать самодокументирующийся код. Это включает правильное именование переменных/классов, постоянный рефакторинг. Как показывает практика, хорошо спроектированный и хорошо написаный код в комментариях не нуждается. Сложные моменты, в которых без комментариев не разобраться, это первые кандидаты на рефакторинг. Если рефакторинг невозможен, например это реализация хитро оптимизированного алгоритма, применяется "литературное программирование": сначала человеческим языком описывается что делается, а потом в текст вставляется код. Делается это до написания, потому как такой код скорее всего меняться не будет, а описанный человеческим языком алгоритм намного упрощает кодирование. Архитектура описывается отдельным документом, в котором зафиксированы принятые архитектурные решения и причины, побудившия принять именно эти решения. Варианты использования описываются модульными тестами, которые также можно использовать в качестве примеров.

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

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

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

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

AVK>Сразу писать, потому что иначе это начинает смахивать на профанацию.
Сразу это когда? Например я пишу их перед комитом. Раньше просто нет смысла ибо у меня методы в процессе кодирования постоянно появляются и исчезают или меняется их функциональность. К тому же для написания комментариев нужно переключить мозги на другой режим работы, а переключать мозги туда сюда не продуктивно к томуже такие переключения сбивают с мысли.

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

WH>Сразу это когда?
Сразу — это перед написанием метода.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Добрый день.

Поясню сабж: процесс кодирования сильно зависит от специфики задачи и общего процесса разроботки (проектирования, тестирования, документирования). Комментарии в этом смысле можно отнести к различным потокам работы (workflow) или скорее к некотрой связке между ними. Поэтому возникает вопрос на каком этапе их писать? Можно писать сразу: закодил метод — закооментировал. Можно после успешной сборки, можно даже перед кодированием, а ля автотесты. Зачастую приходится слышать, как начальство требует комментарии, что лично мне, например, не убобно, потому как код постоянно меняется и их приходится переписывать, на что собственно уходит время. С другой стороны, если их не писать сразу, то потом когда все заработало и продается уже вроде и не надо как-то.

Вот и хочется услышать соображения на этот счет. Поделитесь опытом.

Спасибо.

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

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

А>>Добрый день.

А>>... Поэтому возникает вопрос на каком этапе их писать? ...
А>>Вот и хочется услышать соображения на этот счет. Поделитесь опытом.

M>Непосредственно перед написанием кода.
M>Очень способствует написанию кода, который делает именно то, что нужно, а не то, что сделать проще/удобнее.

А еще лучше перед написанием кода писать тесты.
Тогда точно приходится задуматься над тем, что надо сделать
и как этим пользоваться.

Комментарии же бывают разные.
Интерфейсную часть комментирую сразу.
А детали реализации ближе к концу, если это вообще надо.
Бывает что комментарии просто не нужны, потому что все видно из самого кода.

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

А>Вообще конечно я с этом согласен в идеале. Но на практике порой бывает, что не совсем понятно, что писать...

А>Должен же быть какой-то компромис.

Это да.
Только форум тут философский, потому рассуждаем об идеальных сущностях.
Реальность она частенько другая

С этим я тоже согласен. Но полюбому найдется такой кусок кода, который будет непонятен по коду. Особенно когда дело касается сложных алгоритмов или всеобщих архитектурных решений.

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

MF>Я комментарии почти не делаю, потому что знаю, что они очень быстро рассогласовываются с кодом, к которому они относятся и снижают понятность.
MF>Стараюсь писать self-documenting code, то есть выбираю такие названия для методов переменных и пр. объектов, чтобы из названий было понятно, что это. Например, я никогда не пишу timeout, а всегда timeoutInSeconds или timeoutInMinutes.
MF>Теперь, когда в MSVS 2005 есть рефакторинг, нормальные названия стало давать значительно проще.
MF>Таков мой подход.

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

MF>Стараюсь писать self-documenting code, то есть выбираю такие названия для методов переменных и пр. объектов, чтобы из названий было понятно, что это. Например, я никогда не пишу timeout, а всегда timeoutInSeconds или timeoutInMinutes.

Вероятно забавно выглядят идентификаторы waitResponseTimeoutInMilliseconds или slaveHostConnectionTimeoutInSeconds

А для названий классов и методов есть какие-нибудь правила?

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

E>А для названий классов и методов есть какие-нибудь правила?

Канэшна!
Основных правил два
1. Название должно как можно более адекватно и кратко отражать то, к чему оно относится.
2. Следовать code-naming guidelines от Микрософта (поля на подчеркивание (и приватные, кстати), интерфейсы на I, контролы как nameTextBox или okButton, эвент-хэндлеры — с постфиксом Handler и параметрами вида (sender, EventArgs), протектедный метод OnEvent()).

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

А>С этим я тоже согласен. Но полюбому найдется такой кусок кода, который будет непонятен по коду. Особенно когда дело касается сложных алгоритмов или всеобщих архитектурных решений.

А это надо описывать не комментариями, а в отдельных дизайн-документах.

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

Со сложными алгоритмами точно так же.
Надо писать отдельное описание без сильной привязки к реализации.

bkat wrote:

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

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

E>Вероятно забавно выглядят идентификаторы waitResponseTimeoutInMilliseconds или slaveHostConnectionTimeoutInSeconds

В native API есть вот такая чудная тройка

ZwAccessCheckByTypeAndAuditAlarm
ZwAccessCheckByTypeResultListAndAuditAlarm
ZwAccessCheckByTypeResultListAndAuditAlarmByHandle

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

E>Есть одина область разработки ПО, где такой подход не применим вообще -- разработка библиотек. Написание документации по библиотеки, которую будут использовать разные программисты с разными тараканами в голове -- это очень неблагодарное дело. Но хуже всего, что для библиотеки нужен Reference Manual про ее API. Самый удобный способ получения такого manual-а -- это написание специальных комментариев в коде которые затем обрабатываются специализированным инструментом (JavaDoc, Doxygen, RDoc, DDoc и пр.). Если при разработке библиотки комментарии не писать сразу, то задокументировать ее затем будет весьма трудоемким и, возможно, бесполезным занятием.
Тут лучше сделать сразу две задачи.
1. Задокументировать с помощью Unit-тестов и(или) examples.(чаще полезней чем различные списки интерфейсов)
2. Задокументировать библиотеку, как — уже неважно. К вопросам комментариев мало относится. Как ты документируешь с помощью комментариев или просто вручную написав документ, твое личное дело. И к тому же оно совершенно не касается внутреннего кода.

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

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

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

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

Я помню.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Здравствуйте, 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

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

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

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