向行业公司的遗留应用程序/代码中的代码添加注释？ [关闭]

Question

我是美国一家公司的初级软件工程师。正如你们工程师所知道的那样，很多时候我都会遇到大量未记录的代码，几乎没有/零 cmets（我主要使用 Java 编写代码）。

现在，我知道你可能会说“好吧，评论代码然后老兄！”的逻辑响应，我以前做过，但我注意到整个代码库都没有注释，所以看起来“奇怪”有一些评论方法等等出乎意料。这可能需要更多时间，或者有时我只是缺少有关应用程序或系统如何运行的“宏大”规模的信息，因此我无法发表评论整个代码库或功能。

我想问问你们也有未注释/未记录的遗留应用程序并在行业工作的软件工程师：

1. 当我处理缺陷/错误和新功能时，我应该修复并评论整个代码库
2. 别管它，因为它是一个遗留应用程序，并遵循之前设置的模式（无 cmets）
3. 随着时间的推移，在我处理应用程序时评论各个部分
4. 是像// this is a comment 这样的简单cmets 还是java-doc 风格的cmets？ （下）：

     /**
     * 
     * @param the four byte rgb pixel value from image
     * @return the bitwise AND of the rgb value and a bitmask
     */

谢谢！

Answer 1

事实上，这个问题没有“正确”的答案。我要问的第一个问题是：您的公司或团队是否已就开发实践达成一致？如果是这样，评论实践至少应该在其中顺便提及。有些人认为编写良好的代码是不言自明的，不需要 cmets。那里可能就是这种情况。也可能是他们相信但他们的代码不是不言自明的 - 那将是一个不同的对话。如果团队或部门没有达成一致意见，那么任何你试图做的事情都会失败。

针对您的具体问题：

1. 没有。如果您有一个没有记录或评论的完整代码库，并且您在没有指示或批准的情况下使用它，那么您将花费大量的时间和金钱来完成没有人要求的事情。至少你会让人们对你不满意。最糟糕的是，我见过有人因为这种事情而被解雇。

2. 这可能是一个同样无益的极端。它不一定是全部或全部，这不会改善代码库或真正贡献任何积极的东西，您可能只会让自己感到沮丧。

3. 这可能是最有意义的，但我再次强调，请与您的团队讨论商定的做法。也许在回顾中建议（因为你有一个 scrum 标签），有时间在每个积压项目中为受影响的代码执行此操作。我敢打赌，你不是唯一这样想的人。

4. 有些团队喜欢一个，有些团队喜欢另一个。与人交谈，但最终，这可能并不重要。在我多年的编程中，我看到的主要区别是内联 cmets 做得不好可能会丢失，而如果块 cmets 做得不好，你可能会丢失一些代码。要么做得不好，就很难跟上。做好任何一个都会让事情变得更容易。

Answer 2

您已经得到了很好的答案，但我想补充一点关于 JavaDoc 的内容。

JavaDoc 的值来自自动生成的文档。这在记录 API 之类的内容时特别有用。

您从代码中的部分 JavaDoc 覆盖中获得的价值会减少。例如，仅涵盖 API 一半的 JavaDoc 的价值将远低于涵盖所有 API 的 JavaDoc。