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 ?
 
Подождите ...
Wait...
Пока на собственное сообщение не было ответов, его можно удалить.