Вот здесь

Автор: MxMsk
Дата: 24.10.08
Вопрос: Как частно и полностью ли пишите XML-комментарии в C#?

увидел голосование про комментарии.

Проголосовал за последний вариант, желаю объяснить позицию.

Лучшая документация — это сам код. Комментарии для документации читаются не только в документации, но и в коде.
Т.к. документация пишется в комментарии, "DSL" для неё имеет только одно техническое требование: чтобы оставался комментарием в соответствующем языке. Чем проще и читабельнее, тем лучше.
Вот пример правильного комментария для документации.
http://java.sun.com/j2se/javadoc/writingdoccomments/#format
Можно ещё упростить: вместо @param p1 использовать @p1 и писать менее развёрнуто.
XML же просто замусоривает код своим синтаксическим оверхедом, он не самый лучший язык разметки для данного случая. Convert absloutely everything to XML ?

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

AG>Вот здесь

Автор: MxMsk
Дата: 24.10.08
Вопрос: Как частно и полностью ли пишите XML-комментарии в C#?

увидел голосование про комментарии.

Во блин А я вначале как раз хотел тему создать, потом решил просто голосовалку.
Сейчас я пишу везде, но заметил, что немногие так делают.

AG>Проголосовал за последний вариант, желаю объяснить позицию.

AG>Лучшая документация — это сам код. Комментарии для документации читаются не только в документации, но и в коде.
AG>Т.к. документация пишется в комментарии, "DSL" для неё имеет только одно техническое требование: чтобы оставался комментарием в соответствующем языке. Чем проще и читабельнее, тем лучше.
AG>Вот пример правильного комментария для документации.
AG>http://java.sun.com/j2se/javadoc/writingdoccomments/#format
AG>Можно ещё упростить: вместо @param p1 использовать @p1 и писать менее развёрнуто.
AG>XML же просто замусоривает код своим синтаксическим оверхедом, он не самый лучший язык разметки для данного случая. Convert absloutely everything to XML ?

Описание при помоще XML позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов

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

MK>Описание при помоще XML позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов

Описание на любом заданном языке разметки позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов.

С Intellisense работает даже такая разметка:

struct Point
{
  int x; // абсцисса
  int y; // ордината
}

Для генерации хелпов — стиль javadoc (использую doxygen).

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

AG>Лучшая документация — это сам код. Комментарии для документации читаются не только в документации, но и в коде.
AG>Т.к. документация пишется в комментарии, "DSL" для неё имеет только одно техническое требование: чтобы оставался комментарием в соответствующем языке. Чем проще и читабельнее, тем лучше.
AG>Вот пример правильного комментария для документации.
AG>http://java.sun.com/j2se/javadoc/writingdoccomments/#format
AG>Можно ещё упростить: вместо @param p1 использовать @p1 и писать менее развёрнуто.
AG>XML же просто замусоривает код своим синтаксическим оверхедом, он не самый лучший язык разметки для данного случая. Convert absloutely everything to XML ?

Я вообще считаю этот путь с xml-комментариями в коде неправильным... код замусоривается, да и пригодны такие комментарии только для автоматической генерации статических хелпов. Т.е. только для комментирования готового кода, который долгое время не будет меняться.
У меня давно уже зреет другая идея: в коде пишутся только "ссылки" на комментарии, а сами комментарии живут в отдельных xml/html файлах и образуют доступную для всех разработчиков проекта базу знаний. Пример (для С++, для других языков будет все то же самое )

//[[project1.part2.subpart3.class1.method4]]
void Class1::Method4()
{
 // ..
}

такие комментарии-ссылки подсвечиваются особым образом, и двойной щелчек (или иное действие) на них приводит к загрузке в специальное окно (закладка в нижней области студии — Output, Find Results...) информации, связанной с этим комментарием. Это полноценный html-редактор, там можно редактировать текст комментария , вводить теги для поиска по тегам, ссылаться на другие топики базы знаний и т.д.
Формат комментария еще не определен — возможно, будет так как в примере, может быть просто GUID топика (хотя это совсем не наглядно), там есть некоторые тонкости.

База знаний строится по принципу иерархического дерева с ориентированными на человека именами узлов (в т.ч. на русском языке), с возможностью поиска по тегам (специальная кнопка на тулбаре, специальный диалог поиска, результаты можно отображать в специальной закладке внизу). Дерево должно быть доступно в студии (закладка в области Class View, Solution Explorer...). Двойным щелчком на узле дерева можно перейти в файл и в позицию файла на соответствующий комментарий-ссылку. Так организуется обратная связи "база — код" (что вообще не сделать с помощью автоматически генерируемых хелпов типа doxygen'а !), а база образует гибрид wiki, аутлайнера и именованной иерархической системы bookmark'ов для всего проекта.
Благодаря тому, что отдельные топики и узлы дерева базы хранятся в маленьких html и xml файлах, база полностью пригодна для существования в системе контроля версий, такой как SVN: апдейт скачивает те файлы, которые были закоммичены другими пользователями, а благодаря текстовому формату возможно автоматическое слияние документов.

Здравствуйте, MxKazan, Вы писали:
MK>Описание при помоще XML позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов

XML, особенно в том виде, в каком он используется в C#, слишком уж много оверхеда дает. Мне вот нравится, как в haddock сделано. Пишешь определенного вида комментарий рядом с функцией — он документирует им функцию. Пишешь рядом с типом аргумента — он документирует аргумент.

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

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

MK>>Описание при помоще XML позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов

AG>Описание на любом заданном языке разметки позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов.

AG>С Intellisense работает даже такая разметка:
AG>

AG>struct Point
AG>{
AG>  int x; // абсцисса
AG>  int y; // ордината
AG>}
AG>

AG>Для генерации хелпов — стиль javadoc (использую doxygen).

Так ежели у нас по-любому разметка, чем же тогда плох xml? "Лишними" скобками разве что

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

MC>Здравствуйте, MxKazan, Вы писали:
MK>>Описание при помоще XML позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов

MC>XML, особенно в том виде, в каком он используется в C#, слишком уж много оверхеда дает. Мне вот нравится, как в haddock сделано. Пишешь определенного вида комментарий рядом с функцией — он документирует им функцию. Пишешь рядом с типом аргумента — он документирует аргумент.

Гм. Интересный вариант — избавил бы от необходимости следить, чтобы в тегах <param> были корректные имена.
С другой стороны, тоже не выход — комменты по аргументам захламят описание сигнатуры — будет даже хуже.

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

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

XC>У меня давно уже зреет другая идея: в коде пишутся только "ссылки" на комментарии, а сами комментарии живут в отдельных xml/html файлах
Не увеличит ли это временные затраты на документирование?

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

XC>Здравствуйте, Alexander G, Вы писали:

AG>>Лучшая документация — это сам код. Комментарии для документации читаются не только в документации, но и в коде.
AG>>Т.к. документация пишется в комментарии, "DSL" для неё имеет только одно техническое требование: чтобы оставался комментарием в соответствующем языке. Чем проще и читабельнее, тем лучше.
AG>>Вот пример правильного комментария для документации.
AG>>http://java.sun.com/j2se/javadoc/writingdoccomments/#format
AG>>Можно ещё упростить: вместо @param p1 использовать @p1 и писать менее развёрнуто.
AG>>XML же просто замусоривает код своим синтаксическим оверхедом, он не самый лучший язык разметки для данного случая. Convert absloutely everything to XML ?

XC>Я вообще считаю этот путь с xml-комментариями в коде неправильным... код замусоривается, да и пригодны такие комментарии только для автоматической генерации статических хелпов. Т.е. только для комментирования готового кода, который долгое время не будет меняться.
XC>У меня давно уже зреет другая идея: в коде пишутся только "ссылки" на комментарии, а сами комментарии живут в отдельных xml/html файлах и образуют доступную для всех разработчиков проекта базу знаний. Пример (для С++, для других языков будет все то же самое )
XC>

XC>//[[project1.part2.subpart3.class1.method4]]
XC>void Class1::Method4()
XC>{
XC> // ..
XC>}
XC>

XC>такие комментарии-ссылки подсвечиваются особым образом, и двойной щелчек (или иное действие) на них приводит к загрузке в специальное окно (закладка в нижней области студии — Output, Find Results...) информации, связанной с этим комментарием. Это полноценный html-редактор, там можно редактировать текст комментария , вводить теги для поиска по тегам, ссылаться на другие топики базы знаний и т.д.
XC>Формат комментария еще не определен — возможно, будет так как в примере, может быть просто GUID топика (хотя это совсем не наглядно), там есть некоторые тонкости.

XC>База знаний строится по принципу иерархического дерева с ориентированными на человека именами узлов (в т.ч. на русском языке), с возможностью поиска по тегам (специальная кнопка на тулбаре, специальный диалог поиска, результаты можно отображать в специальной закладке внизу). Дерево должно быть доступно в студии (закладка в области Class View, Solution Explorer...). Двойным щелчком на узле дерева можно перейти в файл и в позицию файла на соответствующий комментарий-ссылку. Так организуется обратная связи "база — код" (что вообще не сделать с помощью автоматически генерируемых хелпов типа doxygen'а !), а база образует гибрид wiki, аутлайнера и именованной иерархической системы bookmark'ов для всего проекта.
XC>Благодаря тому, что отдельные топики и узлы дерева базы хранятся в маленьких html и xml файлах, база полностью пригодна для существования в системе контроля версий, такой как SVN: апдейт скачивает те файлы, которые были закоммичены другими пользователями, а благодаря текстовому формату возможно автоматическое слияние документов.

Тоже вариант вариант — со ссылками. Но он требует большого внимания к актуальности документации. Кстати, можно было бы, например, по ссылке не в окно уходить, а сделать что-то вроде смарт-тега. В-общем, да, в целом нравится, но нужна хорошая поддержка IDE, в том числе со слежением за актуальностью — а то взял, грохнул метод, а про коммент забыл.

Здравствуйте, MxKazan, Вы писали:
MK>С другой стороны, тоже не выход — комменты по аргументам захламят описание сигнатуры — будет даже хуже.

Чтобы не быть голословным — вот пример.

-- | This is the documentation for the 'f' function
f  :: Int      -- ^ The 'Int' argument
   -> Float    -- ^ The 'Float' argument
   -> IO ()    -- ^ The return value
f = <тут уже определение функции>

"--" — Это обычное начало однострочного комментария в хаскеле.
"^" и "|"- Это оверхед от haddock'а (ну кроме необходимости размещать спецификацию функции на нескольких строках).

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

MK>Так ежели у нас по-любому разметка, чем же тогда плох xml? "Лишними" скобками разве что

Да. И не только лишними скобками, но и лишними буквами и линшими значками больше и меньше.
@param someParameter всё ж хуже @someParameter или someParameter, но лучше XML.

Неужели не хочется, чтобы комментарий для системы документирования оставался комментарием для кода ?

Здравствуйте, MxKazan, Вы писали:
MK>Так ежели у нас по-любому разметка, чем же тогда плох xml? "Лишними" скобками разве что
Именно. Лишними скобками, названиями тегов и т.п.

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

MC>Здравствуйте, MxKazan, Вы писали:
MK>>С другой стороны, тоже не выход — комменты по аргументам захламят описание сигнатуры — будет даже хуже.

MC>Чтобы не быть голословным — вот пример.
MC>

MC>-- | This is the documentation for the 'f' function
MC>f  :: Int      -- ^ The 'Int' argument
   ->> Float    -- ^ The 'Float' argument
   ->> IO ()    -- ^ The return value
MC>f = <тут уже определение функции>
MC>

MC>"--" — Это обычное начало однострочного комментария в хаскеле.
MC>"^" и "|"- Это оверхед от haddock'а (ну кроме необходимости размещать спецификацию функции на нескольких строках).

Более реальный вариант:

// Initializes a new instance of the Binding class that binds the indicated control property to the specified data member of the specified data source.
// Optionally enables formatting, propagates values to the data source based on the specified update setting, and sets the property to the specified value
// when a DBNull is returned from the data source.
public Binding(
    string propertyName,    // The name of the control property to bind.
    Object dataSource,    // An Object representing the data source.
    string dataMember,    // The property or list to bind to.
    bool formattingEnabled, // true to format the displayed data; otherwise, false.
    Object nullValue    // The Object to be applied to the bound control property if the data source value is DBNull.
)

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

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

MK>

MK>// Initializes a new instance of the Binding class that binds the indicated control property to the specified data member of the specified data source.
MK>// Optionally enables formatting, propagates values to the data source based on the specified update setting, and sets the property to the specified value
MK>// when a DBNull is returned from the data source.
MK>public Binding(
MK>    string propertyName,    // The name of the control property to bind.
MK>    Object dataSource,    // An Object representing the data source.
MK>    string dataMember,    // The property or list to bind to.
MK>    bool formattingEnabled, // true to format the displayed data; otherwise, false.
MK>    Object nullValue    // The Object to be applied to the bound control property if the data source value is DBNull.
MK>)
MK>

MK>Не улавливаю, чем это лучше XML'а?
Это читается легче, читатель имеет дело только с синтаксисом языка и человеческим языком, но не с синтаксисом докогенерилки.

MK>Как быть, если у меня будет длинный тип параметра и длинное имя.
Писать столько строк, сколько надо.

MK>Как быть, если я в описании функции захочу сослаться на параметр?
так и сылаться, без разметки, это забота генерилки ловить ссылки.

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

XC>У меня давно уже зреет другая идея: в коде пишутся только "ссылки" на комментарии, а сами комментарии живут в отдельных xml/html файлах и образуют доступную для всех разработчиков проекта базу знаний.

Ну, в шарпе как раз таки такая возможность есть. Редактор для отдельных файлов к студии прикрутить совсем несложно.

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

MK>// Initializes a new instance of the Binding class that binds the indicated control property to the specified data member of the specified data source.
MK>// Optionally enables formatting, propagates values to the data source based on the specified update setting, and sets the property to the specified value
MK>// when a DBNull is returned from the data source.
MK>public Binding(
MK>    string propertyName,    // The name of the control property to bind.
MK>    Object dataSource,    // An Object representing the data source.
MK>    string dataMember,    // The property or list to bind to.
MK>    bool formattingEnabled, // true to format the displayed data; otherwise, false.
MK>    Object nullValue    // The Object to be applied to the bound control property if the data source value is DBNull.
MK>)
MK>

MK>Не улавливаю, чем это лучше XML'а?
Меньше писать, меньше читать. При этом выразительность не страдает.

MK>Как быть, если у меня будет длинный тип параметра и длинное имя.
ССЗБ. Еще один повод использовать удобочитаемые и удобонаписаемые (ака в меру короткие) имена.

MK>Как быть, если я в описании функции захочу сослаться на параметр?
Забота самого "документатора". Хотя в haddock вроде такого нет. Впрочем — и не особо надо. Описание параметра и так будет в пределах досягаемости — от гиперссылки пользы не будет.

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

MK>Не улавливаю, чем это лучше XML'а?
MC>Меньше писать, меньше читать. При этом выразительность не страдает.
Сейчас сигнатура не смешивается с каментами. А предлагается наоборот, всё в одну кучу свалить.
Подобный вариант также вынуждает каждый параметр писать с новой строки.

MK>>Как быть, если я в описании функции захочу сослаться на параметр?
MC>Забота самого "документатора". Хотя в haddock вроде такого нет. Впрочем — и не особо надо. Описание параметра и так будет в пределах досягаемости — от гиперссылки пользы не будет.
И в С# ссылки не будет. Дело в том, что по итоговому форматированию в хелпе можно понять, что подразумевается под словом в предложении — термин или имя параметра.

Здравствуйте, MxKazan, Вы писали:
MK>Сейчас сигнатура не смешивается с каментами. А предлагается наоборот, всё в одну кучу свалить.
Сейчас — это где? Я привел пример того, как при использовании haddock описание смешивается с сигнатурой. По-моему получается неплохо.

MK>Подобный вариант также вынуждает каждый параметр писать с новой строки.
Вы так говорите, как будто это что-то плохое.

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

MC>Здравствуйте, x-code, Вы писали:

XC>>да и пригодны такие комментарии только для автоматической генерации статических хелпов. Т.е. только для комментирования готового кода, который долгое время не будет меняться.
MC>Хм... почему это? Наоборот, внося изменения в код, удобнее по ходу дела подправить расположенные рядом комментарий, чем лезть в какую-то базу.

XC>>У меня давно уже зреет другая идея: в коде пишутся только "ссылки" на комментарии, а сами комментарии живут в отдельных xml/html файлах
MC>Не увеличит ли это временные затраты на документирование?

Я это представляю так: создаю новый метод (или вижу старый, без документации). Тыкаю мышью в точку, в которой должен быть комментарий-ссылка, и нажимаю специальную кнопку на тулбаре, или выбираю команду из контекстного меню, или нажимаю сочетание клавиш (насколько я понимаю, API аддинов к современным студиям все это позволяет). Тут же открывается модальное окно, в котором мне предлагается выбрать позицию комментария к дереву (причем дерево уже раскрыто в той же позиции, что и дерево базы на закладке рядом с Class View). Я выбираю родительский узел, корректирую имя нового узла (которое по умолчанию устанавливается в имя объекта под курсором — простейший парсинг одной строки кода!) и нажимаю ОК, тут же диалог закрывается и открывается редактор html в нижней части студии.

Затраты минимальны (клик — выбор в дереве — клик), если учесть что не под диктовку код пишу, а думаю... А для таких языков как C# можно отказаться даже от выбора узла дерева, сделав вариант дерева, соответствующего естественной иерархии пространств имен и классов проекта. Это будет другая кнопка на тулбаре — и всего один клик.

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

MK>Тоже вариант вариант — со ссылками. Но он требует большого внимания к актуальности документации. Кстати, можно было бы, например, по ссылке не в окно уходить, а сделать что-то вроде смарт-тега. В-общем, да, в целом нравится, но нужна хорошая поддержка IDE, в том числе со слежением за актуальностью — а то взял, грохнул метод, а про коммент забыл.

Сделать функцию "поиска битых ссылок" — не проблема А вообще, я не планирую зацикливаться на комментировании кода, см. здесь

Автор: x-code
Дата: 24.10.08

.
В случае если метод грохнули а комментарий забыли — скорее всего будет меняться статус комментария, что визуально будет выглядеть как другая пиктограмма узла в дереве. А при отображении дерева можно будет пользоваться каким-то фильтром — какие узлы показывать: комментарии к коду, свободные комментарии, комментарии к удаленному коду, векторные диаграммы UML (их тоже много!), векторные диаграммы MindMaps, таблицы, ссылки на внешние файлы и т.д...