Хорошо ли использовать #region в каждом методе, который мы реализуем? - PullRequest
Новая
       6

Хорошо ли использовать #region в каждом методе, который мы реализуем?

2 голосов
/ 01 марта 2011

Недавно мой менеджер проекта попросил написать комментарии, резюме и # регионы для всей работы, которую мы проделали до сих пор.Даже он попросил написать для объявления переменной тоже.Например, если мы объявим сумму как двойную, он попросил нас написать так: 

  /// <summary>
    /// RegularPay declared as double
    /// </summary>
    private double m_dRegularPay;

И даже для Get Set тоже 

  /// <summary>
    /// Get and Set FirstName
    /// </summary>
    public string FirstName
    {
        get
        {
            return m_sFirstName;
        }
        set
        {
            m_sFirstName = value;
        }
    }

И регионы при реализации некоторого кода 

   #region EmpHourly
    /// <summary>
    /// Get Employe Hourly Amount
    /// </summary>
    /// <param name="EmpAmount"></param>
    /// <param name="EmpRegularHours"></param>
    /// <param name="EmpHourlyRate"></param>
    /// <param name="EmpBonusPay"></param>
    /// <param name="EmpOtherHours"></param>
    /// <param name="EmpOverTimeHours"></param>
    /// <returns></returns>
    public bool GetEmpHourlyAmount(out double EmpAmount, out double EmpRegularHours, out double EmpHourlyRate, out double EmpBonusPay, out int EmpOtherHours, out int EmpOverTimeHours)
    {
     }

Что я хочу знать, так это лучший способ кодирования стандартов

Ответы [ 11 ]

12 голосов
/ 01 марта 2011

Комментирование полей и свойств класса - хорошая практика, но регион здесь кажется бессмысленным.Я также добавлю, что чрезмерное использование переменных является не очень хорошим стилем C #.Вам лучше вернуть объект.

6 голосов
/ 01 марта 2011

Это соглашение о комментировании кажется чрезмерно усердным ... но непоследовательно.

Глупо занято аннотировать строку double RegularPay комментарием «RegularPay объявлен как двойной». Это очевидно, и указание на это является излишним и пустой тратой времени.

В вашем регионе сводка по GetEmpHourlyAmount может быть важной, но она не рассматривается как таковая. Название метода так же полезно, как и комментарий.

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

6 голосов
/ 01 марта 2011

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

Я также думаю, что запрос на комментирование в школе заслуживает откат. Это добавляет нулевое значение, создает занятость и скрывает реальные комментарии (которые представляют собой сам код). 

/// <summary>
/// RegularPay declared as double
/// </summary>
private double m_dRegularPay;

Это говорит об одном и том же три раза. В комментарии говорится, что RegularPay является удвоенным, что private double RegularPay является частным double, и что оплата m_dRegular является частным double.

На самом деле, комментарий и запись указывают, что в какой-то момент времени m_dRegularPay был удвоен. Закрытые двойные идентификаторы утверждают, что это все еще закрытый двойник. 

private double regularPay;

Это гласит только один раз.

3 голосов
/ 01 марта 2011

Мне кажется, это слишком много.

Документирование методов / переменных с самоописанием ради их документирования - пустая трата денег. Они устаревают и затрудняют чтение кода.

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

Документация и регионы не исправят плохой код и не усложнят его обслуживание. Хороший код самоописывается, и ему не нужны общие правила, такие как «комментировать все».

Комментируйте, где это уместно, и используйте регионы в качестве предупреждающего знака о том, что вам нужно исправить структуру вашего файла.

3 голосов
/ 01 марта 2011

IMO Регионы - это кодовый запах. Они влияют на readability, а также maintainability. Вам нужны регионы, когда есть большой кодовый файл и вам нужно разделить код на части. Тем не менее, вы действительно должны писать маленькие классы, каждый из которых выполняет свою задачу.

При редактировании файлов кода с регионами, очень трудно решить, в какой регион вы хотите поместить свои новые методы и т. Д. Я часто видел, что во многих регионах содержится код, который должен принадлежать другому региону.

Комментировать свойства хорошо, но вы должны также написать цель \ использование свойства, чтобы сделать вещи более понятными. В идеале цель должна быть очевидна из самого названия.

Я думаю, что бессмысленно писать комментарии, например, «поле объявлено как double». Интеллектуальная среда IDE уже делает работу, делая комментарий излишним.

Также рассмотрите возможность использования auto properties для удаления стандартного кода.

2 голосов
/ 01 марта 2011

Эти комментарии могут использоваться для автоматического создания документации для кода.Проконсультируйтесь с менеджером проекта, так ли это.

Я согласен с другими, что комментировать то, что очевидно, является пустой тратой времени.Регулярная оплата, являющаяся двойным, является одним таким комментарием.Пример или другая информация, которая не сразу очевидна, была бы более полезной.Например, «обычная оплата в неделю» или «обычная оплата в год» или «обычная оплата в центах».Эти комментарии были бы необходимы, потому что никто в здравом уме не назовет переменную RegularPayPerWeekInCentsExclusionOvertimeRatesAndTaxDeductions.

2 голосов
/ 01 марта 2011

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

Вместо «Получить и установить имя», если там действительно должен быть комментарий, я мог бы изменить его на что-то вроде «Получает или задает имя сотрудника».

Вместо "RegularPay рассчитывается как двойной", я бы ... ну ... лучшее имя для переменной. VS позволяет легко переименовывать переменную и настолько просто навести курсор мыши на переменную и посмотреть, что это такое, что лучшей документацией будет сам код в более наглядном виде.

Что касается #region s, если в области будет содержаться значительно больше одного метода, тогда может помочь область с четким названием . Однако для отдельных методов это не стоит усилий - VS может уже свернуть методы, когда вам угодно, поэтому #region добавляет шум и ничего не дает.

2 голосов
/ 01 марта 2011

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

1 голос
/ 01 марта 2011

Комментирующая переменная, как вы сделали, не будет иметь смысла, поскольку она неявно показывает действительность. 

   private double m_dRegularPay;

говорит все это

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

0 голосов
/ 09 сентября 2013
  1. Область, вероятно, никогда не должна использоваться внутри функции или содержать только одну функцию - достаточно простого комментария или блока. Если ваша функция кажется слишком большой, возможно, вам стоит подумать о рефакторинге. Регион может иметь смысл для реализации интерфейса , если ваш класс реализует более одного интерфейса.
  2. Класс, вероятно, никогда не должен содержать только одну область. В противном случае область - это просто класс (возможно, у вас уже есть комментарий или блок для класса), так что это просто дублирует информацию.
  3. Поместите область вокруг ваших объявлений частных переменных - это зависит от вашего стиля программирования, я размещаю все свои частные объявления в верхней части класса, и в 99% случаев, когда я открываю файл, я изменяю функцию или свойство поэтому нет необходимости видеть их, если я не создаю что-то новое, поэтому для меня имеет смысл разместить их в регионе.

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

Страница:
...