在行业公司的遗留 apps/code 代码中添加注释？
Adding comments to code in legacy apps/code at company in industry?
我是美国一家公司的初级软件工程师。正如你们工程师所知，很多时候我 运行 进入了大量未记录的代码，几乎没有 no/zero 注释（我大部分代码都是 Java）。
现在，我知道您可能会说“好吧，先注释代码然后老兄！”这样的合乎逻辑的回答，我以前也这样做过，但我注意到整个代码库都没有注释，因此看起来“很奇怪”有一些评论方法等等。这可能需要更多的时间，或者有时我只是缺乏关于应用程序或系统如何运行的“大”规模的信息，所以我会 not 能够评论整个代码库或功能。
我想问问你们那些也有 uncommented/undocumented 遗留应用程序并在工业界工作的软件工程师，如果：
- 我应该在 修复 并评论 整个 代码库 defects/bugs 和新功能
- 不要管它，因为它是遗留应用程序，并遵循之前设置的模式（无评论）
- 在我处理应用程序的过程中对各个部分发表评论
- 喜欢
// 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
*/
谢谢！
事实是，这个问题没有“正确”答案。我要问的第一个问题是：贵公司或团队是否已就开发实践达成一致？如果是这样，评论实践至少应该在其中顺便提及。有些人认为编写良好的代码是不言自明的，不需要注释。那里可能就是这种情况。也可能是他们相信但他们的代码不是不言自明的——那将是一个不同的对话。在团队或部门中没有达成一致将使您尝试做的任何事情都失败。
针对您的具体问题：
没有。如果你有一个没有记录或评论的完整代码库，并且你在没有指导或批准的情况下使用它，那么你将花费天文数字的时间和金钱来做一些没有人要求的事情。至少你会让人们对你不高兴。最糟糕的是，我见过有人因为这种事情被解雇。
这可能是一个同样无益的极端。它不一定是全有或全无，这不会改进代码库或真正贡献任何积极的东西，你可能只会让自己感到沮丧。
这可能是最有道理的，但我再次强调，与您的团队讨论商定的做法。也许在回顾中建议（因为你有一个 scrum 标签）每个积压项目都有时间为受影响的代码做这件事。我打赌你不是唯一有这种想法的人。
有些团队喜欢一个，有些团队喜欢另一个。与人交谈，但最终，这可能并不重要。在我多年的编程生涯中，我看到的主要区别是行内注释做得不好可能会丢失，而块注释做得不好，你可能会丢失代码片段。任何一个做得不好都会让人更难遵循。两者都做得好会让事情变得更容易。
您已经有了很好的答案，但我想补充一点关于 JavaDoc 的内容。
JavaDoc 的值来自自动生成的文档。这在记录 API.
之类的内容时特别有用
代码中的部分 JavaDoc 覆盖率会降低您的价值。例如，仅涵盖 API 一半内容的 JavaDoc 的价值远低于涵盖所有内容的 JavaDoc。
我是美国一家公司的初级软件工程师。正如你们工程师所知，很多时候我 运行 进入了大量未记录的代码，几乎没有 no/zero 注释（我大部分代码都是 Java）。
现在，我知道您可能会说“好吧，先注释代码然后老兄！”这样的合乎逻辑的回答，我以前也这样做过，但我注意到整个代码库都没有注释，因此看起来“很奇怪”有一些评论方法等等。这可能需要更多的时间，或者有时我只是缺乏关于应用程序或系统如何运行的“大”规模的信息，所以我会 not 能够评论整个代码库或功能。
我想问问你们那些也有 uncommented/undocumented 遗留应用程序并在工业界工作的软件工程师，如果：
- 我应该在 修复 并评论 整个 代码库 defects/bugs 和新功能
- 不要管它，因为它是遗留应用程序，并遵循之前设置的模式（无评论）
- 在我处理应用程序的过程中对各个部分发表评论
- 喜欢
// 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
*/
谢谢！
事实是，这个问题没有“正确”答案。我要问的第一个问题是：贵公司或团队是否已就开发实践达成一致？如果是这样，评论实践至少应该在其中顺便提及。有些人认为编写良好的代码是不言自明的，不需要注释。那里可能就是这种情况。也可能是他们相信但他们的代码不是不言自明的——那将是一个不同的对话。在团队或部门中没有达成一致将使您尝试做的任何事情都失败。
针对您的具体问题：
没有。如果你有一个没有记录或评论的完整代码库，并且你在没有指导或批准的情况下使用它，那么你将花费天文数字的时间和金钱来做一些没有人要求的事情。至少你会让人们对你不高兴。最糟糕的是，我见过有人因为这种事情被解雇。
这可能是一个同样无益的极端。它不一定是全有或全无，这不会改进代码库或真正贡献任何积极的东西，你可能只会让自己感到沮丧。
这可能是最有道理的，但我再次强调，与您的团队讨论商定的做法。也许在回顾中建议（因为你有一个 scrum 标签）每个积压项目都有时间为受影响的代码做这件事。我打赌你不是唯一有这种想法的人。
有些团队喜欢一个，有些团队喜欢另一个。与人交谈，但最终，这可能并不重要。在我多年的编程生涯中，我看到的主要区别是行内注释做得不好可能会丢失，而块注释做得不好，你可能会丢失代码片段。任何一个做得不好都会让人更难遵循。两者都做得好会让事情变得更容易。
您已经有了很好的答案，但我想补充一点关于 JavaDoc 的内容。
JavaDoc 的值来自自动生成的文档。这在记录 API.
之类的内容时特别有用代码中的部分 JavaDoc 覆盖率会降低您的价值。例如，仅涵盖 API 一半内容的 JavaDoc 的价值远低于涵盖所有内容的 JavaDoc。