使用代码注释将用户表达的需求与代码联系起来是个好主意吗？

Question

我有一个文档，其中我使用 REQxxx 作为每个需求的 ID 来指定用户需求。有时在源代码中我得出结论，一个特定的代码块对应于一个特定的需求，所以我写这样的东西

        // append TestStepResultEntity only for the Step Result View RQ001
        if( !(newEntity instanceof TestScenarioResultEntity && this.getUserObject() instanceof TestSuiteResultEntity))
            for (Object item : ((RootEntity<?, ?>) newEntity).getItems())
                newNode.NewItemAddedToEntityEventHappened(item);

这是代码创意吗？关于这些事情有什么最佳实践吗？？

Answer 1

我个人会在单元测试或验收测试中加入此类信息，例如有一个名为

的测试

@Test
public void shouldAppendTestStepResultEntityOnlyForTheStepResultView_RQ001() {
    ...
}

测试应证明要求已实现，并将以对未来开发人员有用的方式记录您的代码（某种）。

Answer 2

If/when 要求发生变化，这些类型的评论很少更新 - 这意味着我不知道评论是否仍然有效或现在已过时，甚至可能是错误和误导的。

当需求发生变化并相应更新时，我或许可以对 REQ123 进行文本搜索，但这似乎是官僚主义的开销，并且可能会很快退化。尤其是在大型团队中。

将此与解释代码块实际作用的评论进行比较：我经常可以 - 无需咨询其他系统 - 很快就能看到评论是否仍然有效。在这种情况下，我更有可能编辑注释，从而提高代码质量。

话虽如此，这些评论可能（如前所述）在验收测试中有意义。

使用代码注释将用户表达的需求与代码联系起来是个好主意吗？

is linking between requirement expressed by user and code using code comment a good idea?

java

specifications