Поскольку присвоение имени unit test делает его цель более значимой, необходимо ли добавить сводку к методу unit test?
Пример:
/// <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()
{
...
}
Я думаю, что длинное описательное имя более важно, чем комментарий XML. Поскольку unit test не будет частью 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-интерфейсов и фреймворков.
Я действительно предпочитаю использовать атрибут DescriptionAttribute над сводным тегом. Причина в том, что значение атрибута Description будет отображаться в файле результатов. Это облегчает понимание сбоев, когда вы просто смотрите на файл журнала
[TestMethod,Description("Ensure feature X doesn't regress Y")]
public void TestFeatureX42() {
..
}
Лично я стараюсь сделать тесты достаточно простыми, чтобы прочитать, что документация будет излишней. Я использую встроенные комментарии в методе тестирования, чтобы объяснить, почему я делаю что-то конкретным образом, а не то, что я делаю.
Не нужно, но если вы чувствуете, что комментарии XML добавляют значение выше и выше самого имени unit test (которое выглядит как всеобъемлющее), вы будете делать другим разработчикам сервис.
Если сводка по существу является прямым дубликатом имени метода unit test, то я думаю, что это перебор.
В приведенном выше примере я бы сказал, что это не обязательно, если вы не используете инструмент, который извлекает документацию из источника (например, javadoc или что-то еще).
Обычное эмпирическое правило состоит в том, что в коде говорится, что вы делаете, и в комментарии говорится, почему, но так как имя настолько многословное (что, я думаю, все в порядке, поскольку никто никогда не должен его вводить) Не думаю, что комментарий вносит свой вклад.
Необходимо добавить резюме, когда сводка может предоставить дополнительную информацию, которая может/должна быть закодирована в имени метода. Обратите внимание, что когда я говорю "необходимо" при обращении к какой-либо документации, я имею в виду "необходимо передать 100% необходимого контекста/деталей/нюансов новому кодеру, наследующему проект, или вам самому через 5 лет".
Комментарий XML совершенно не нужен, если у вас есть описательное имя метода. И это необходимо для методов единичного тестирования.
Вы уже на правильном пути, имея имя описательного метода тестирования. (Многие гибкие и TDD-практики считают, что метод тестирования должен включать "должен", например, как показано в ссылку на текст в этом сообщении в блоге.
Лично мне нравятся имена методов вроде этого:
MyClass_OnInvalidInput_ShouldThrowFormatException()
Но это только мои личные предпочтения.
Если вы считаете, что это лучшее использование вашего времени, сделайте это, иначе нет. Я бы не хотел.