Как комментировать / документировать переопределение в C #? - PullRequest
Новая
       30

Как комментировать / документировать переопределение в C #?

3 голосов
/ 29 марта 2012

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

В прошлом я писал что-то вроде этого, чтобы показать намерение обойти базовый метод : 

protected override void OnMouseUp(MouseEventArgs e)
{
    // base.OnMouseUp(e);
}

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

Но я хочу сделать лучше:

  • Как мне задокументировать намерение переопределения?, в частности:
  • Что мне записать в документации переопределения XML (<summary>?) ?

Ответы [ 3 ]

5 голосов
/ 29 марта 2012

Для документации я бы просто использовал встроенные теги документации : 

/// <summary>Exiting drag mode on mouse up</summary>
protected override void OnMouseUp(MouseEventArgs e)
{
    ...

Для уточнения намерения я бы просто добавил комментарий типа 

protected override void OnMouseUp(MouseEventArgs e)
{
    // not calling the base implementation
    ...
}

Линия 

// base.OnMouseUp(e);

создает впечатление, что звонок временно закомментирован (и, возможно, кто-то забыл восстановить его обратно)

3 голосов
/ 29 марта 2012

комментарий как 

// This method is intentionally blank because 
// we do not want the base class functionality

намного лучше, чем 

// base.SomeMethod();

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

Если у вас есть контроль над базовым классом, может быть лучше удалить этот метод и сделать класс более абстрактным. Тогда вы можете реализовать эту функцию только в дочерних классах там, где это необходимо.

1 голос
/ 29 марта 2012

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

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

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

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

...