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

问题描述

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

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

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

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

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

谢谢！

解决方法

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

针对您的具体问题：

1. 没有。如果您有一个没有记录或注释的完整代码库，并且您在没有指导或批准的情况下接受它，那么您将花费大量的时间和金钱来做没有人要求的事情。至少你会让人们对你感到不安。最糟糕的是，我见过有人因为这种事情被解雇。

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

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

4. 有些团队喜欢一个，有些团队喜欢另一个。与人交谈，但最终，这可能无关紧要。在我多年的编程生涯中，我看到的主要区别是内联注释做得不好可能会丢失，而块注释做得不好时，您可能会丢失代码片段。做得不好都会让人更难跟上。两者都做好会让事情变得更容易。

,

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

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

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