Требуется ли резюме в методе модульного тестирования?

Question

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

Пример:

/// <summary>
/// Check the FormatException should be thrown when a give country data line contains a invalid number.
/// </summary>
[TestMethod]
public void FormatException_Should_Thrown_When_Parse_CountryLine_Containing_InvalidNumber()
{
  ...
}

Answer 1

Я на самом деле предпочитаю использовать Атрибут Description вместо итогового тега. Причина в том, что значение атрибута Description будет отображаться в файле результатов. Это упрощает понимание ошибок, когда вы просто просматриваете файл журнала

[TestMethod,Description("Ensure feature X doesn't regress Y")]
public void TestFeatureX42() {
  ..
}

Answer 2

Я думаю, что длинное описательное имя более важно, чем комментарий XML. Поскольку юнит-тест не будет частью API, вам не нужен XML-комментарий.

Например:

[TestMethod]
public void FormatException_Should_Thrown_When_Parse_CountryLine_Containing_InvalidNumber()
{
  ...
}

полезнее, чем:

///<summary>
/// Exception Should Thrown When Parse CountryLine Containing InvalidNumber
///</summary>
[TestMethod]
public void Test42()
{
  ...
}

Комментарии XML следует использовать для документирования API и фреймворков.

Answer 3

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

Answer 4

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

Вы уже на правильном пути, имея имя описательного метода тестирования. (Многие практики Agile и TDD считают, что метод тестирования должен включать «следует», например, как показано в текст ссылки в этом сообщении в блоге.

Лично мне нравятся такие имена методов:

MyClass_OnInvalidInput_ShouldThrowFormatException()

Но это всего лишь мое личное предпочтение.

Answer 5

Необходимо добавить сводку, когда сводка может предоставить больше информации, которая может / должна быть закодирована в имени метода. Обратите внимание, что когда я говорю «необходимо» при обращении к какой-либо документации, я имею в виду «необходимо передать 100% необходимого контекста / деталей / нюансов новому кодировщику, унаследовавшему проект, или вам самому 5 лет спустя».

Answer 6

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

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

Answer 7

Если вы думаете, что это лучшее использование вашего времени, сделайте это, иначе не делайте. Я бы не стал.

Answer 8

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

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