Делаем XML-комментарии обязательными

14 мая 2009 г.

Маленькая уловка, которая поможет команде осознать, что XML-комментарии в коде действительно обязательны.

После выставления этих опций в свойствах проекта на каждый публичный объект без XML-комментария (класс, метод, свойство и т.д.) выдается ошибка компиляции:

Надеюсь, что этот пример поможет вам, если вы, как и я, пытались внедрить в команду культуру написания XML-комментарием.

23 комментария:

  1. Полностью с тобой согласен, это очень правильная и нужная практика.
    Подход ОБЯЗАТЕЛЬНЫХ комментариев нужен везде, кроме слоя представления данных в веб-проектах.

    ОтветитьУдалить
  2. Если уж говорить именно о комментариях, то нужно ставить Specific Warnings, вместо All

    ОтветитьУдалить
  3. @dotnet
    Спасибо за уточнение. Вообще, я придерживаюсь мнения, что warning-ов тоже не должно быть ;0

    ОтветитьУдалить
  4. Есть такая утилитка gHostDoc http://www.roland-weigelt.de/ghostdoc/ - которая довольно таки очень неплохо составляет XML комментарии, анализируя название метода - очень сильно облегчает добавление XML комментариев

    ОтветитьУдалить
  5. Спасибо за ссылку. Скорее всего она хорошо подойдет для расставления комментариев в унаследованном коде. А ты для чего ее использовал(а)?

    ОтветитьУдалить
  6. Да, это просто замечательный способ наполнить свой код мешающими для понимания комментариями вида:
    ///<summary></summary>

    Я вот у себя прививаю другую привычку: читать код, а не комменты, и писать код так, чтобы комменты были преимущественно не нужны.
    Наличие комментария — это всегда исключение из правила.

    ОтветитьУдалить
  7. @xoposhiy
    Это способ показать, что комментарии важны для тебя, а за пустые скобки для отмазки придется отвечать и искать причину почему так получилось.

    Комментарии в коде действительно являются признаком того, что код надо рефакторить. Но я говорю о других комментариях. Они могу дать понять разработчикам _как_ использовать твою библиотеку.

    При использовании .NET ты же смотришь какой параметр за что отвечает, а это XML тэг: param name="...

    ОтветитьУдалить
  8. > Спасибо за ссылку. Скорее всего она хорошо подойдет для расставления комментариев в унаследованном коде. А ты для чего ее использовал(а)?

    Я его использую во всех своих проектах - и тех которые с нуля пишутся.

    Примеры "автокомментариев" (заменил "<" на "[" так как не позволяет иначе публиковать):

    /// [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)

    т.е. очень выручает для основной массы кода - когда назначение очевидно - но анализатор кода обязательно требует добавление комментариев, что довольно сильно экономит время разработчика на комментировании вполне очевидных по назначению простых методов. (Кстати - у меня студия требует комментариев именно из за включения всех правил анализатора кода).

    ОтветитьУдалить
  9. @Ахмед
    Выглядит интересно!

    С другой стороны комментарии, написанные человеком, как-то "живее" выглядят. Например, можно описать некоторую особенность объекта или пример его использования.

    ОтветитьУдалить
  10. > С другой стороны комментарии, написанные человеком, как-то "живее" выглядят. Например, можно описать некоторую особенность объекта или пример его использования.

    Да, конечно - он предназнчен для коментирования простых методов - например он не комментирует классы - так как скзать что этот класс делает и для чего он преднозначен и что он дает из одного только названия невозможно сказать из одного только названия.

    ОтветитьУдалить
  11. @Ахмед
    Ну и зачем нужны комментарии в коде, которые итак однозначно восстанавливаются по коду?
    userId — the user Id.
    Да, я как бы догадался, что это the user Id и без комментария. Зачем мне 80% тупых комментариев в коде?

    Я вижу только одну причину появления таких проектов по генерации комментариев. Соответствующая настройка в VisualStudio запрещающая их не писать ;)

    Ещё раз, посыл: давайте писать хорошие комментарии, чтобы нашу систему было проще использовать. Продолжение: а чтобы не тратить на это время, давайте использовать автогенератор булшит-комментариев. Возвращаясь к посылу понимаем, что получили вовсе не то, что хотели.

    ОтветитьУдалить
  12. @xoposhiy
    Я понимаю, что с людьми не надо бороться техническими средствами. В данном случае я, конечно, отдаю себе отчет, что выставление таких настроек в VS можно обойти =)

    Но, раз я уделил этому время, акцентировал на комментариях внимание команды, пускай таким способом, то _не_ писать комментарии становится как-то неудобно.

    А за такой комментарий, конечно, надо по рукам бить:
    // создание объекта
    var obj = new object();
    И так в глазах от букв рябит, дак еще и очевидные вещи подписывают! =)

    На прошлой своей работе особо "выдающиеся" комментарии я даже выносил в общее wiki (без указания на автора).

    ОтветитьУдалить
  13. ОК. На самом деле моя позиция такова:
    В проектах, не являющихся библиотеками такой подход вреден, ибо ухудшает читаемость кода и принуждает программистов к противоестественному.

    XML-комментарии в библиотеках, которые будут использоваться многими людьми такой подход действительно может быть оправдан.

    Тул для автоматической генерации XML-булшит-комментариев не бывает полезным вообще никогда. ;)

    ОтветитьУдалить
  14. @xoposhiy
    Согласен. Хочу только уточнить.

    "принуждает программистов к противоестественному" - это ты про написание комментариев? =)

    ОтветитьУдалить
  15. Когда уверен в товарищах по команде, можно оставить написание только Summary, чтобы SRP не профукать.

    А комментарии к публичным методам все-таки overkill, если мы не фреймворк сознательно пишем.

    ОтветитьУдалить
  16. Есть еще очень полезные тэги. Например, returns и exception.

    ОтветитьУдалить
  17. Интересный, но спорный метод борьбы с отсутствием комментариев. Способ верный, но иногда лучше полное отсутствие комментариев, чем какой-нибудь абсолютно не лаконичный, длинный и сложный комментарий. Формальный процесс, инспекции кода - вот, пожалуй, действенное решение. Но дорогое.

    ОтветитьУдалить
  18. @Михаил
    Да, я тоже не люблю технических средств борьбы против привычек разработчиков.

    "Формальный процесс, инспекции кода - вот, пожалуй, действенное решение"
    Согласен, поэтому мы используем парное программирование, т.е. постоянную инспекцию кода.

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

    ОтветитьУдалить
  19. @Михаил
    А как часто вы проводите инспекции кода? Является ли это формальным процессом с определенным списком проверок? Кто (в какой должности) этим занимается?

    ОтветитьУдалить
  20. Александр,

    Парное программирование - это неплохо. Но у меня нет такой практики.

    Проведение и назначение инспекций у нас было чисто формальным процессом. Были закреплены объекты инспекций, их размер (в листах, в строках кода), также было формально закреплены время подготовки к инспекциям, состав инспекции, формален был и итог инспекции. Роли участников инспекции и их должности (высокая должность - это было фактом необязательным, нужен был авторитет и знание предмета) тоже были формально закреплены. Велись и тренинги о инспекциях. Вообщем, довольно сложный и дорогой процесс разработки ПО.

    ОтветитьУдалить
  21. Очень советую парное программирование. Много плюсов, один из которых это улучшение качества кода.

    Хорошее описание code review я нашел в книжке Code Craft. В принципе, по этому описанию мы и проводил свои инспекции кода.

    А вообще... http://www.veracode.com/blog/2008/02/new-unit-of-reviews-code-quality

    ОтветитьУдалить
  22. человеческие коды пахнут жизнью :)

    ОтветитьУдалить

Моя книга «Антихрупкость в IT»

Как достигать результатов в IT-проектах в условиях неопределённости. Подробнее...