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

По поводу голосования — у нас обязательность XML-комментариев прописана в кодестайле, и за их отсутствие при code review тут же получаешь по шапке. Соответственно, вариантов не остаётся
Re[2]: XML комментарии
От: MxKazan Россия  
Дата: 27.10.08 07:46
Оценка:
Здравствуйте, andy1618, Вы писали:

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


Ага. Работал в фирме с таким же подходом. Очень правильным, я считаю
Re[2]: XML комментарии
От: Alexander G Украина  
Дата: 27.10.08 08:35
Оценка:
Здравствуйте, 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-привет системам генерации документации
Русский военный корабль идёт ко дну!
Re[3]: XML комментарии
От: andy1618 Россия  
Дата: 03.11.08 12:25
Оценка:
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 и, в частности, исполняемые модели. Но на практике пока не пробовал.
Подождите ...
Wait...
Пока на собственное сообщение не было ответов, его можно удалить.