Маленькая уловка, которая поможет команде осознать, что XML-комментарии в коде действительно обязательны.
После выставления этих опций в свойствах проекта на каждый публичный объект без XML-комментария (класс, метод, свойство и т.д.) выдается ошибка компиляции:
Надеюсь, что этот пример поможет вам, если вы, как и я, пытались внедрить в команду культуру написания XML-комментарием.
Полностью с тобой согласен, это очень правильная и нужная практика.
ОтветитьУдалитьПодход ОБЯЗАТЕЛЬНЫХ комментариев нужен везде, кроме слоя представления данных в веб-проектах.
Если уж говорить именно о комментариях, то нужно ставить Specific Warnings, вместо All
ОтветитьУдалить@dotnet
ОтветитьУдалитьСпасибо за уточнение. Вообще, я придерживаюсь мнения, что warning-ов тоже не должно быть ;0
Есть такая утилитка gHostDoc http://www.roland-weigelt.de/ghostdoc/ - которая довольно таки очень неплохо составляет XML комментарии, анализируя название метода - очень сильно облегчает добавление XML комментариев
ОтветитьУдалитьСпасибо за ссылку. Скорее всего она хорошо подойдет для расставления комментариев в унаследованном коде. А ты для чего ее использовал(а)?
ОтветитьУдалитьДа, это просто замечательный способ наполнить свой код мешающими для понимания комментариями вида:
ОтветитьУдалить///<summary></summary>
Я вот у себя прививаю другую привычку: читать код, а не комменты, и писать код так, чтобы комменты были преимущественно не нужны.
Наличие комментария — это всегда исключение из правила.
@xoposhiy
ОтветитьУдалитьЭто способ показать, что комментарии важны для тебя, а за пустые скобки для отмазки придется отвечать и искать причину почему так получилось.
Комментарии в коде действительно являются признаком того, что код надо рефакторить. Но я говорю о других комментариях. Они могу дать понять разработчикам _как_ использовать твою библиотеку.
При использовании .NET ты же смотришь какой параметр за что отвечает, а это XML тэг: param name="...
> Спасибо за ссылку. Скорее всего она хорошо подойдет для расставления комментариев в унаследованном коде. А ты для чего ее использовал(а)?
ОтветитьУдалитьЯ его использую во всех своих проектах - и тех которые с нуля пишутся.
Примеры "автокомментариев" (заменил "<" на "[" так как не позволяет иначе публиковать):
/// [summary]
/// Handles the Load event of the Page control.
/// [/summary]
/// [param name="sender"]The source of the event.[/param]
/// [param name="e"]The [see cref="System.EventArgs"/] instance containing the event data.[/param]
protected void Page_Load(object sender, EventArgs e)
/// [summary]
/// Adds the token.
/// [/summary]
/// [param name="userId"]The user id.[/param]
/// [param name="authToken"]The auth token.[/param]
/// [param name="sharedID"]The shared ID.[/param]
public void AddToken(Guid userId, string authToken, string sharedID)
/// [summary]
/// Enables processing of HTTP Web requests by a custom HttpHandler that implements the [see cref="T:System.Web.IHttpHandler"/] interface.
/// [/summary]
/// [param name="context"]An [see cref="T:System.Web.HttpContext"/] object that provides references to the intrinsic server objects (for example, Request, Response, Session, and Server) used to service HTTP requests.[/param]
public void ProcessRequest(HttpContext context)
т.е. очень выручает для основной массы кода - когда назначение очевидно - но анализатор кода обязательно требует добавление комментариев, что довольно сильно экономит время разработчика на комментировании вполне очевидных по назначению простых методов. (Кстати - у меня студия требует комментариев именно из за включения всех правил анализатора кода).
@Ахмед
ОтветитьУдалитьВыглядит интересно!
С другой стороны комментарии, написанные человеком, как-то "живее" выглядят. Например, можно описать некоторую особенность объекта или пример его использования.
> С другой стороны комментарии, написанные человеком, как-то "живее" выглядят. Например, можно описать некоторую особенность объекта или пример его использования.
ОтветитьУдалитьДа, конечно - он предназнчен для коментирования простых методов - например он не комментирует классы - так как скзать что этот класс делает и для чего он преднозначен и что он дает из одного только названия невозможно сказать из одного только названия.
@Ахмед
ОтветитьУдалитьСогласен!
@Ахмед
ОтветитьУдалитьНу и зачем нужны комментарии в коде, которые итак однозначно восстанавливаются по коду?
userId — the user Id.
Да, я как бы догадался, что это the user Id и без комментария. Зачем мне 80% тупых комментариев в коде?
Я вижу только одну причину появления таких проектов по генерации комментариев. Соответствующая настройка в VisualStudio запрещающая их не писать ;)
Ещё раз, посыл: давайте писать хорошие комментарии, чтобы нашу систему было проще использовать. Продолжение: а чтобы не тратить на это время, давайте использовать автогенератор булшит-комментариев. Возвращаясь к посылу понимаем, что получили вовсе не то, что хотели.
@xoposhiy
ОтветитьУдалитьЯ понимаю, что с людьми не надо бороться техническими средствами. В данном случае я, конечно, отдаю себе отчет, что выставление таких настроек в VS можно обойти =)
Но, раз я уделил этому время, акцентировал на комментариях внимание команды, пускай таким способом, то _не_ писать комментарии становится как-то неудобно.
А за такой комментарий, конечно, надо по рукам бить:
// создание объекта
var obj = new object();
И так в глазах от букв рябит, дак еще и очевидные вещи подписывают! =)
На прошлой своей работе особо "выдающиеся" комментарии я даже выносил в общее wiki (без указания на автора).
ОК. На самом деле моя позиция такова:
ОтветитьУдалитьВ проектах, не являющихся библиотеками такой подход вреден, ибо ухудшает читаемость кода и принуждает программистов к противоестественному.
XML-комментарии в библиотеках, которые будут использоваться многими людьми такой подход действительно может быть оправдан.
Тул для автоматической генерации XML-булшит-комментариев не бывает полезным вообще никогда. ;)
@xoposhiy
ОтветитьУдалитьСогласен. Хочу только уточнить.
"принуждает программистов к противоестественному" - это ты про написание комментариев? =)
Когда уверен в товарищах по команде, можно оставить написание только Summary, чтобы SRP не профукать.
ОтветитьУдалитьА комментарии к публичным методам все-таки overkill, если мы не фреймворк сознательно пишем.
Есть еще очень полезные тэги. Например, returns и exception.
ОтветитьУдалитьИнтересный, но спорный метод борьбы с отсутствием комментариев. Способ верный, но иногда лучше полное отсутствие комментариев, чем какой-нибудь абсолютно не лаконичный, длинный и сложный комментарий. Формальный процесс, инспекции кода - вот, пожалуй, действенное решение. Но дорогое.
ОтветитьУдалить@Михаил
ОтветитьУдалитьДа, я тоже не люблю технических средств борьбы против привычек разработчиков.
"Формальный процесс, инспекции кода - вот, пожалуй, действенное решение"
Согласен, поэтому мы используем парное программирование, т.е. постоянную инспекцию кода.
Способ, который я описал несет целью не заставить разработчиков раз и навсегда писать комментарии, а показать, что для меня действительно важно, чтобы комментарии были написаны.
@Михаил
ОтветитьУдалитьА как часто вы проводите инспекции кода? Является ли это формальным процессом с определенным списком проверок? Кто (в какой должности) этим занимается?
Александр,
ОтветитьУдалитьПарное программирование - это неплохо. Но у меня нет такой практики.
Проведение и назначение инспекций у нас было чисто формальным процессом. Были закреплены объекты инспекций, их размер (в листах, в строках кода), также было формально закреплены время подготовки к инспекциям, состав инспекции, формален был и итог инспекции. Роли участников инспекции и их должности (высокая должность - это было фактом необязательным, нужен был авторитет и знание предмета) тоже были формально закреплены. Велись и тренинги о инспекциях. Вообщем, довольно сложный и дорогой процесс разработки ПО.
Очень советую парное программирование. Много плюсов, один из которых это улучшение качества кода.
ОтветитьУдалитьХорошее описание code review я нашел в книжке Code Craft. В принципе, по этому описанию мы и проводил свои инспекции кода.
А вообще... http://www.veracode.com/blog/2008/02/new-unit-of-reviews-code-quality
человеческие коды пахнут жизнью :)
ОтветитьУдалить