XML комментарии
От: Alexander G Украина  
Дата: 24.10.08 10:50
Оценка: +2
Вот здесь
Автор: MxMsk
Дата: 24.10.08
Вопрос: Как частно и полностью ли пишите XML-комментарии в C#?
увидел голосование про комментарии.

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

Лучшая документация — это сам код. Комментарии для документации читаются не только в документации, но и в коде.
Т.к. документация пишется в комментарии, "DSL" для неё имеет только одно техническое требование: чтобы оставался комментарием в соответствующем языке. Чем проще и читабельнее, тем лучше.
Вот пример правильного комментария для документации.
http://java.sun.com/j2se/javadoc/writingdoccomments/#format
Можно ещё упростить: вместо @param p1 использовать @p1 и писать менее развёрнуто.
XML же просто замусоривает код своим синтаксическим оверхедом, он не самый лучший язык разметки для данного случая. Convert absloutely everything to XML ?
Русский военный корабль идёт ко дну!
Re: XML комментарии
От: MxKazan Россия  
Дата: 24.10.08 10:56
Оценка:
Здравствуйте, 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'ов
Re[2]: XML комментарии
От: Alexander G Украина  
Дата: 24.10.08 11:04
Оценка: +1
Здравствуйте, MxKazan, Вы писали:

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


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

С Intellisense работает даже такая разметка:
struct Point
{
  int x; // абсцисса
  int y; // ордината
}

Для генерации хелпов — стиль javadoc (использую doxygen).
Русский военный корабль идёт ко дну!
Re: XML комментарии
От: x-code  
Дата: 24.10.08 12:07
Оценка: -1
Здравствуйте, 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: апдейт скачивает те файлы, которые были закоммичены другими пользователями, а благодаря текстовому формату возможно автоматическое слияние документов.
Re[2]: XML комментарии
От: Mr.Cat  
Дата: 24.10.08 12:11
Оценка:
Здравствуйте, MxKazan, Вы писали:
MK>Описание при помоще XML позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов

XML, особенно в том виде, в каком он используется в C#, слишком уж много оверхеда дает. Мне вот нравится, как в haddock сделано. Пишешь определенного вида комментарий рядом с функцией — он документирует им функцию. Пишешь рядом с типом аргумента — он документирует аргумент.
Re[3]: XML комментарии
От: MxKazan Россия  
Дата: 24.10.08 12:25
Оценка:
Здравствуйте, 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? "Лишними" скобками разве что
Re[3]: XML комментарии
От: MxKazan Россия  
Дата: 24.10.08 12:25
Оценка:
Здравствуйте, Mr.Cat, Вы писали:

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

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

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


Гм. Интересный вариант — избавил бы от необходимости следить, чтобы в тегах <param> были корректные имена.
С другой стороны, тоже не выход — комменты по аргументам захламят описание сигнатуры — будет даже хуже.
Re[2]: XML комментарии
От: Mr.Cat  
Дата: 24.10.08 12:30
Оценка: +2
Здравствуйте, x-code, Вы писали:

XC>да и пригодны такие комментарии только для автоматической генерации статических хелпов. Т.е. только для комментирования готового кода, который долгое время не будет меняться.

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

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

Не увеличит ли это временные затраты на документирование?
Re[2]: XML комментарии
От: MxKazan Россия  
Дата: 24.10.08 12:37
Оценка:
Здравствуйте, 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, в том числе со слежением за актуальностью — а то взял, грохнул метод, а про коммент забыл.
Re[4]: XML комментарии
От: Mr.Cat  
Дата: 24.10.08 12:40
Оценка:
Здравствуйте, 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'а (ну кроме необходимости размещать спецификацию функции на нескольких строках).
Re[4]: XML комментарии
От: Alexander G Украина  
Дата: 24.10.08 12:43
Оценка: +1
Здравствуйте, MxKazan, Вы писали:

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


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

Неужели не хочется, чтобы комментарий для системы документирования оставался комментарием для кода ?
Русский военный корабль идёт ко дну!
Re[4]: XML комментарии
От: Mr.Cat  
Дата: 24.10.08 12:46
Оценка: +1
Здравствуйте, MxKazan, Вы писали:
MK>Так ежели у нас по-любому разметка, чем же тогда плох xml? "Лишними" скобками разве что
Именно. Лишними скобками, названиями тегов и т.п.
Re[5]: XML комментарии
От: MxKazan Россия  
Дата: 24.10.08 12:50
Оценка:
Здравствуйте, 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'а?
Как быть, если у меня будет длинный тип параметра и длинное имя.
Как быть, если я в описании функции захочу сослаться на параметр?
Re[6]: XML комментарии
От: Alexander G Украина  
Дата: 24.10.08 13:01
Оценка: +1
Здравствуйте, 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>Как быть, если я в описании функции захочу сослаться на параметр?

так и сылаться, без разметки, это забота генерилки ловить ссылки.
Русский военный корабль идёт ко дну!
Re[2]: XML комментарии
От: AndrewVK Россия http://blogs.rsdn.org/avk
Дата: 24.10.08 13:23
Оценка:
Здравствуйте, x-code, Вы писали:

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


Ну, в шарпе как раз таки такая возможность есть. Редактор для отдельных файлов к студии прикрутить совсем несложно.
... << RSDN@Home 1.2.0 alpha 4 rev. 1111 on Windows Vista 6.0.6001.65536>>
AVK Blog
Re[6]: XML комментарии
От: Mr.Cat  
Дата: 24.10.08 13:45
Оценка: +1
Здравствуйте, 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 вроде такого нет. Впрочем — и не особо надо. Описание параметра и так будет в пределах досягаемости — от гиперссылки пользы не будет.
Re[7]: XML комментарии
От: MxKazan Россия  
Дата: 24.10.08 14:09
Оценка:
Здравствуйте, Mr.Cat, Вы писали:

MK>Не улавливаю, чем это лучше XML'а?

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

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

MC>Забота самого "документатора". Хотя в haddock вроде такого нет. Впрочем — и не особо надо. Описание параметра и так будет в пределах досягаемости — от гиперссылки пользы не будет.
И в С# ссылки не будет. Дело в том, что по итоговому форматированию в хелпе можно понять, что подразумевается под словом в предложении — термин или имя параметра.
Re[8]: XML комментарии
От: Mr.Cat  
Дата: 24.10.08 14:23
Оценка:
Здравствуйте, MxKazan, Вы писали:
MK>Сейчас сигнатура не смешивается с каментами. А предлагается наоборот, всё в одну кучу свалить.
Сейчас — это где? Я привел пример того, как при использовании haddock описание смешивается с сигнатурой. По-моему получается неплохо.

MK>Подобный вариант также вынуждает каждый параметр писать с новой строки.

Вы так говорите, как будто это что-то плохое.
Re[3]: XML комментарии
От: x-code  
Дата: 24.10.08 18:40
Оценка:
Здравствуйте, Mr.Cat, Вы писали:

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


XC>>да и пригодны такие комментарии только для автоматической генерации статических хелпов. Т.е. только для комментирования готового кода, который долгое время не будет меняться.

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

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

MC>Не увеличит ли это временные затраты на документирование?

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

Затраты минимальны (клик — выбор в дереве — клик), если учесть что не под диктовку код пишу, а думаю... А для таких языков как C# можно отказаться даже от выбора узла дерева, сделав вариант дерева, соответствующего естественной иерархии пространств имен и классов проекта. Это будет другая кнопка на тулбаре — и всего один клик.
Re[3]: XML комментарии
От: x-code  
Дата: 24.10.08 18:52
Оценка:
Здравствуйте, MxKazan, Вы писали:

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


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