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

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

如果/当需求发生变化时，这些类型的注释很少更新 - 这意味着我不知道该注释是否仍然有效或现在已过时，甚至可能是错误和误导性的。

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

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

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