Вот здесь

Автор: 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, таблицы, ссылки на внешние файлы и т.д...

Лично мне XML-комментарии (C# + VS2005) нравятся по следующим причинам:
0) удобство переименования идентификаторов — если в XML-комментарии все идентификаторы отмечать как ссылки (<see cref=""/>, <paramref name=""/>, ...), то при переименовании через F2/Refactor будет гарантироваться целостность этих ссылок
1) когда вызываешь какой-то метод, тебе во всплывающем окошке выводится чёткое описание из блока summary. Если стараться писать этот блок не тавтологично (т.е. не тупо повторять слова из названия метода, а пояснять его суть), то эта подсказка очень помогает.
2) студия сама генерит практически всю обёртку XML при вводе трёх слешей (///)
3) можно использовать дополнительные теги (exception, refactor, example) для дальнейшего документирования кода.

По поводу голосования — у нас обязательность XML-комментариев прописана в кодестайле, и за их отсутствие при code review тут же получаешь по шапке. Соответственно, вариантов не остаётся

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

A>По поводу голосования — у нас обязательность XML-комментариев прописана в кодестайле, и за их отсутствие при code review тут же получаешь по шапке. Соответственно, вариантов не остаётся

Ага. Работал в фирме с таким же подходом. Очень правильным, я считаю

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

A>Лично мне XML-комментарии (C# + VS2005) нравятся по следующим причинам:
A>0) удобство переименования идентификаторов — если в XML-комментарии все идентификаторы отмечать как ссылки (<see cref=""/>, <paramref name=""/>, ...), то при переименовании через F2/Refactor будет гарантироваться целостность этих ссылок
A>2) студия сама генерит практически всю обёртку XML при вводе трёх слешей (///)
A>3) можно использовать дополнительные теги (exception, refactor, example) для дальнейшего документирования кода.

То есть нравится само документирование и его интеграция с рефакторингом ?
А сам формат XML нравится, или если бы было похож на javadoc был бы лучше ?

A>1) когда вызываешь какой-то метод, тебе во всплывающем окошке выводится чёткое описание из блока summary. Если стараться писать этот блок не тавтологично (т.е. не тупо повторять слова из названия метода, а пояснять его суть), то эта подсказка очень помогает.

Поделись опытом как это удаётся. В смысле для каждого метода написать полезный комментарий.

Также, что думаешь про "literate programming" ?

A>По поводу голосования — у нас обязательность XML-комментариев прописана в кодестайле, и за их отсутствие при code review тут же получаешь по шапке. Соответственно, вариантов не остаётся

Было такое и у меня, только с doxygen-комментариями. В результате большинство из них были как boilearte код. Когда кто-то другой читает код, он всегда может догадаться по именам метода,класса,параметров что там, то что неочевидно, можно глянуть в реализации. Более полезно было бы комментировать что в целом происходит, и почему решили делать именно так, также пояснять "странные" моменты кода, являющиеся ворэраундами для неочевидных проблем... в общем обычные комментарии, а не комментарии для генерилки. Следует также помнить, что внутренние классы, зависящие на сиюминутное требование заказчика — это не библиотека для повторного использования.

В общем, я считаю, что разумнее требовать свободное комментирование кода там, где оно необходимо, чем требовать заполнения тегов документации. В связи с этим, передаю XML-привет системам генерации документации

AG>То есть нравится само документирование и его интеграция с рефакторингом ?

Ага. Плюс упомянутые ниже всплывающие подсказки.


AG>А сам формат XML нравится, или если бы было похож на javadoc был бы лучше ?

Мне кажется, принципиальной разницы нет. Но про слово "XML" знают все, а про "javadoc" — не очень


A>>1) когда вызываешь какой-то метод, тебе во всплывающем окошке выводится чёткое описание из блока summary. Если стараться писать этот блок не тавтологично (т.е. не тупо повторять слова из названия метода, а пояснять его суть), то эта подсказка очень помогает.

AG>Поделись опытом как это удаётся. В смысле для каждого метода написать полезный комментарий.

Например, для метода "GetMaxItemCount" вряд ли есть смысл в summary писать "Gets maximum item count". Лучше написать другими словами: "Gets maximum number of items, that may be stored in the collection without memory reallocation." (пример надуманный, но суть должная быть ясна).
Соответственно, при инспектировании кода ревьюеры должны обращать на это внимание.
Кстати, пока до конца не понятен момент с языком комментариев — писать на английском типа круто (мало ли кому придётся этот код использовать), но зато на русском комментарии получаются более полные и осмысленные.


AG>Также, что думаешь про "literate programming" ?

Да, вкратце читал, вещь прикольная. Правда, меня больше впечатлил подход MDA и, в частности, исполняемые модели. Но на практике пока не пробовал.