在unit testing方法中需要总结
由于unit testing方法的命名使其目的更有意义,是否有必要将摘要添加到unit testing方法中?
例:
/// /// Check the FormatException should be thrown when a give country data line contains a invalid number. /// [TestMethod] public void FormatException_Should_Thrown_When_Parse_CountryLine_Containing_InvalidNumber() { ... }
我认为长描述性名称比XML注释更重要。 由于unit testing不会成为API的一部分,因此您不需要XML注释。
例如:
[TestMethod] public void FormatException_Should_Thrown_When_Parse_CountryLine_Containing_InvalidNumber() { ... }
比以下更有用:
/// /// Exception Should Thrown When Parse CountryLine Containing InvalidNumber /// [TestMethod] public void Test42() { ... }
XML注释应该用于记录API和框架。
我实际上更喜欢在摘要标记上使用DescriptionAttribute。 原因是Description属性的值将显示在结果文件中。 当您只是查看日志文件时,它会使故障更容易理解
[TestMethod,Description("Ensure feature X doesn't regress Y")] public void TestFeatureX42() { .. }
就个人而言,我尝试使测试足够容易阅读文档将是多余的。 我在测试方法中使用内联注释来解释为什么我以某种特定的方式做某事,而不是我正在做的事情。
没有必要,但如果你觉得XML注释增加了超出unit testing本身名称的价值(看起来很全面),那么你将为其他开发人员提供服务。
如果摘要基本上是unit testing方法名称的直接副本,那么我认为这是过度的。
对于上面的例子,我会说没有必要,除非你使用从源代码提取文档的工具(比如javadoc或其他东西)。
一个常见的经验法则是代码说明你正在做什么,评论说明为什么,但因为名字非常冗长(我认为没关系,因为没有人必须输入它)我不认为评论有贡献。
当摘要可以提供可以/应该在方法名称中编码的更多信息时,有必要添加摘要。 请注意,当我在提及任何文档时说“必要”时,我的意思是“必须向inheritance该项目的新编码人员或5年后自己传达100%所需的背景/细节/细微差别”。
如果您有描述性方法名称,则完全不需要XML注释。 这对于unit testing方法来说是必须的。
您已经在正确的轨道上拥有描述性测试方法名称。 (许多敏捷和TDD从业者认为测试方法应该包括“应该”,例如,如本博文中的链接文本所示。
就个人而言,我喜欢这样的方法名称:
MyClass_OnInvalidInput_ShouldThrowFormatException()
但这仅仅是我个人的偏好。
如果您认为这是最好的利用时间,那就去做吧,否则不行。 我不会。