Поле должно иметь заголовок документации - запах кода стиля "Код - код"?

Я только что запустил стиль cop против моего кода и получил несколько:

SA1600: The field must have a documentation header.

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

    /// <summary>
    /// blah blah blah
    /// </summary>

до вершины каждой переменной. Я уверен, что я помню, как кто-то сказал (Мартин Фаулер, Кент Бек... не помню ATM), что комментарий должен сказать "почему" не "что", и я действительно не могу понять, как вы можете объяснить, почему на переменная.

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

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

Кто-нибудь еще находит комментирующие переменные немного запаха кода или это только я.

Ответы

Ответ 1

Я бы не сказал, что комментирование переменной всегда является запахом кода (и это не похоже на то, что вы говорите, либо). Я согласен с тем, что комментируя каждую переменную, каждый раз, по крайней мере, чрезмерно, и, возможно, указывает на плохое присвоение имен. Фактически, некоторые утверждают, что любой комментарий является запахом кода, и что описательные имена и короткие процедуры более читабельны и предотвращают ситуацию, когда код был изменен, но комментарии не были обновлены (что, безусловно, укусило меня в несколько устаревших кодовых баз). Я не думаю, что я бы воспринял это довольно далеко, но если вы можете написать код, который не требует объяснений, без лишних объяснений, это кажется предпочтительным.

Так что да, в основном то, что ты сказал.

Ответ 2

Это довольно старый пост, но натолкнулся на него, ища решение этой проблемы самостоятельно, поэтому, хотя я бы предложил решение.

Если вы откроете файл Settings.StyleCop в редакторе правил, выберите Правила документа node, а затем в разделе Подробные настройки справа отмените опцию Включить поля. Теперь вам больше не потребуется документировать поля.

Ответ 3

Комментарии XML немного отличаются от других комментариев.

Если вы правильно настроите настройки, вы можете отобразить их в подсказках инструментов в Visual Studio и использовать их для создания документации стиля MSDN с Sand Castle. Я думаю, они должны сказать вам, что делает это, когда у вас нет доступа к исходному коду.

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

Я не знаю о инструменте "Cop", который вы используете, но было бы неплохо иметь способ сигнализировать инструменту, который намерен оставить параметр пустым. Итак:

    /// <param name="fubar"></param>  // Haven't gotten around to it
    /// <param name="portNumber" />   // I intend this parameter to have no help

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

    /// <param name="portNumber">The Port Number</param> // What else could it be?

Если вы не хотите использовать вышеописанные функции, выключите правило Style Cop.

Ответ 4

Полностью согласен и первое, что я отключил в StyleCop. Если вам нужно это объяснить, вы назвали его таким образом, который нуждается в объяснении и не удалось сделать код самодокументирование.

Ответ 5

Для тех, кто все еще сталкивается с этой проблемой, этот пост how-to-change-a-stylecop-rule действительно имеет идеальный ответ.

Ответ 6

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

Ответ 7

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