Questions tagged «comments»

许多人声称“评论应解释“为什么”，而不是“如何””。其他人则说“代码应该是自我记录的”，注释应该很少。罗伯特·C·马丁（Robert C. Martin）声称（用我自己的话改写）经常“评论是写得不好的代码的道歉”。 我的问题如下： 解释复杂的算法或带有描述性注释的冗长而复杂的代码段有什么问题？ 这样，无需其他开发人员（包括您自己）逐行阅读整个算法来弄清楚算法的作用，他们只需阅读您用普通英语编写的友好描述性注释即可。 英语是“设计”成易于人类理解的。但是，Java，Ruby或Perl旨在平衡人类可读性和计算机可读性，从而损害了文本的人类可读性。人可以更快地理解英语，而他/她可以理解具有相同含义的代码（只要操作不琐碎）。 因此，在编写了用部分人类可读的编程语言编写的复杂代码之后，为什么不添加友好而易懂的英语的描述性简明注释来解释代码的操作呢？ 有人会说“代码不难理解”，“使函数变小”，“使用描述性名称”，“不要编写意大利面条式代码”。 但是我们都知道这还不够。这些仅是准则-重要且有用的准则- 但它们并不能改变某些算法很复杂的事实。因此在逐行阅读它们时很难理解。 用一些关于它的一般操作的注释来解释一个复杂的算法真的很糟糕吗？用注释解释复杂的代码有什么问题？

236 programming-practices  documentation  comments 

我的团队成员之一一直避免在自己的代码中发表评论。 他的代码不是自记录文档，其他程序员很难理解他的代码。 我已经问过他几次以评论他的代码，但是他只是借口或声称他以后会这样做。他担心的是，添加评论将花费太多时间，并会延迟项目。 我可以向他提出什么论据以说服他正确记录他的代码？ 关于这一点，我错在专注于代码注释吗？或者这表明应该解决更大的问题吗？

182 teamwork  team  comments 

我曾在一家生产至关重要的软件的商店工作过，还处理过一些注释规则，这些规则旨在保持代码的可读性并可能挽救生命。以我的经验，尽管要求变成了脑筋急转弯的工作，需要从清单中剔除，但这并不能帮助我专注于编写可理解的代码。这也分散了我的同行审阅者的注意力，使我无法就如何使代码更易于理解进行更有意义的对话。 我还对没有注释的学生代码进行了评分，并查看了为什么应将它们标记为忽略它们。 我知道使用好名，使结构简单，函数简短，并关注模块将使代码易于理解，从而可以最小化注释。 我也理解注释应该解释为什么代码会执行此操作，而不是如何执行。 鉴于所有这些，甚至有可能编写出能够抓住这一想法的良好编码标准？与同行评审有关但不会变成漫不经心的清单活动，不会产生比以下内容更有用的注释：“您忘了在第42行发表评论”。 在清单中被视为一行时，此规则可能需要的代码示例： /* Display an error message */ function display_error_message( $error_message ) { /* Display the error message */ echo $error_message; /* Exit the application */ exit(); } /* -------------------------------------------------------------------- */ /* Check if the configuration file does not exist, then display an error */ /* …

142 coding-standards  comments  standards  naming-standards  standardization 

我的一个同事认为，任何使用代码内注释（即，不是javadoc样式方法或类注释）都是一种代码气味。你怎么看？

100 comments  anti-patterns 

初级开发人员在这里。 我目前正在为我公司的大客户开发Web应用程序。我上个月开始的。客户希望在其每个软件项目中至少获得25％的评论。 我检查了以前的应用程序的代码，这是我的观察结果： 每个文件都以注释块开头（程序包，最后更新日期，我的公司名称和版权） 所有变量均以其名称注释 // nameOfCustomer public String nameOfCustomer 所有的getter和setter方法都被评论了 很少有用的评论 似乎开发人员只是提出了尽可能多的评论，以达到25％的门槛，无论质量和实用性如何。我的公司告诉我，“我们按照客户的要求去做”。 我没有直接与客户谈论此事。到目前为止，这是我的论点： 没用的线来读书和写字（浪费时间） 注释有时未更新（造成混淆的原因） 开发人员不太可能使用或信任真正有用的评论 您对这个问题有何建议？我应该如何处理这种情况？

96 project-management  comments  client-relations  hierarchy 

我正在做一个相当大的项目，并承担了为它做一些翻译的任务。有很多标签没有被翻译，当我浏览代码时，我发现了这小段代码 //TODO translations 这让我想到了对自己（和其他人？）的这些评论的意义，因为我感觉到大多数开发人员在完成某些代码后，就会按照原本应该做的去做，直到他们拥有完为止进行维护或添加新功能。因此，这TODO将丢失很长时间。 编写此注释是否有意义，还是应该将其写在白板/纸上/其他仍以开发人员为重点的地方？

86 documentation  comments 

我正在与新同事讨论有关评论的问题。我们俩都喜欢Clean Code，并且我完全可以避免内联代码注释，并且应该使用类和方法名称来表示它们的作用，这一点我完全满意。 但是，我非常喜欢添加小类摘要，以尝试解释类的目的和实际代表的内容，主要是为了使其易于维护单一职责原则模式。我也习惯在方法中添加单行摘要，以说明该方法应该执行的操作。一个典型的例子是简单的方法 public Product GetById(int productId) {...} 我添加以下方法摘要 /// <summary> /// Retrieves a product by its id, returns null if no product was found. /// </summary 我认为应该记录该方法返回null的事实。想要调用方法的开发人员不必打开我的代码即可查看该方法是否返回null或引发异常。有时它是接口的一部分，因此开发人员甚至都不知道正在运行哪个基础代码？ 但是，我的同事认为，这类注释是“ 代码异味 ”，“注释始终是失败的”（Robert C. Martin）。 有没有一种方法可以表达和交流这些类型的知识而无需添加评论？由于我是Robert C. Martin的忠实粉丝，所以我有点困惑。摘要与注释相同，因此总是失败吗？ 这不是有关在线注释的问题。

83 comments  clean-code 

我写了以下代码： if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } 这里有一个注释行。但是我认为，通过使if和之间的区别显而易见，可以使代码更清晰else。颜色突出显示的差异更加明显。 这样的代码注释掉是个好主意吗？

83 documentation  comments 

首先，在这个问题上，我想避免争论源代码注释是好是坏。我只是想更清楚地了解人们在谈论可以告诉您原因，原因或方式的评论时的意思。 我们经常看到诸如“注释应该告诉您为什么；代码本身应该告诉您如何”之类的准则。很容易就抽象的观点达成一致。但是，人们通常会像教条一样掉下来，离开房间而无需进一步解释。我已经看到它在许多不同的地方和环境中使用过，看起来人们可以就流行语达成共识，但是他们似乎完全是在谈论不同的事情。 因此，回到问题所在：如果评论可以告诉您原因，那么我们在说什么呢？这就是为什么这段代码首先存在的原因吗？这是片段代码应该做什么？如果有人可以给出清楚的解释，然后添加一些好的示例，我将不胜感激（确实不需要坏的示例，但是可以随意添加它们以进行对比）。 关于评论是好是坏，有很多问题，但是没有人能解决一个具体问题，即什么是可以告诉您为什么的好的评论示例。

78 documentation  comments 

我知道可以将Subversion（我们在工作中使用的东西）配置为要求对提交进行注释，但是我无法简单地将其打开。我知道我对提交进行评论的原因是因为它（即使只是作为慢跑者）对于快速了解提交背后的原因很有用。但是，这似乎还不足以与我经常得到的两个回答作斗争： 它花费的时间太长，我只想将我的更改放入存储库中。 只需看一下差异就很容易了。 我什至向他们展示了简单地输入JIRA问题ID以及它如何自动与问题联系在一起的价值，但仍然与他们无关。 最糟糕的是，可以拨打电话的人在同一个阵营中：不想打扰，并且可以看差异。 我知道这是正确的做法，但是如何让他们看到光线呢？即使我无法说服我的开发人员，我又如何说服管理层这对企业是正确的呢？

78 version-control  comments 

我的老板正在教我（我刚上完学，他想找一个有一点编程经验的人，所以他选择我来培训我该公司的专业知识），并开始使用ASP.NET MVC应用程序，一些HTML和CSS 。我对他给我的网页设计资料感到满意（无需弄清楚，就很容易理解）。 但是例如，他给我一个与ASP.NET MVC有关的任务，他的解释很好。但是他没有在他给我的代码中解释任何内容。（我们在Visual Studio 2013中使用源代码管理），因此它实际上是几百行代码，而对它应该做什么没有任何背景知识。我所看到的那种代码是我从未见过的代码，因此很难弄清楚。 我会尝试问他更多的问题，但是他一直在工作（这是他自己的事），我觉得他可能会被我遇到的所有这些问题烦恼。 因此，只有在我对事物有所了解之前，可以帮助我解决问题的方法，如何才能要求老板在他给我的代码中添加注释，但要礼貌些？

72 comments 

人们XXX在评论中看到的一般含义是什么。有时，我会看到这样的评论： # XXX - This widget really should frobulate the whatsit 当然，我可以说出评论的含义，但是XXX通常是什么意思？是说“这是黑客”还是“也许我们以后应该重温”？还是完全说了其他话？

71 comments  coding-standards 

我只是发现自己在我正在编写的某些代码（旧式Visual Basic 6.0）中写了以下评论： If WindowState <> 1 Then 'The form's not minimized, so we can resize it safely '... End if 我不确定为什么在评论中下意识地使用“我们”。我怀疑这是因为我想象有人在逐步执行代码，就像他们实际上在“执行”每一行上的所有命令一样，而不是仅仅看着它们发生了。以这种心态，我本可以使用I can resize it，因为我是目前正在“做”的那个人，或者you can resize it好像我正在与将来正在“做”的那个人说话，但是由于这两种情况最有可能碰巧，我使用“我们”，就好像我在引导别人通过我的代码一样。 我可以简单地将其重写为it can be resized并避免出现此问题，但这激起了我的好奇心：在评论中使用这样的第一人称是常见的，还是被认为分散了注意力和/或不专业？

63 comments  coding-standards 

背景 我正在一个团队中实施零停机时间部署。为了实现此目标，我们正计划使用蓝/绿部署策略。我在进行研究时意识到的一件事是进行数据库更改变得多么复杂。重命名列之类的简单操作可能需要3个完整的发布周期，直到完成！ 在我看来，全面实施变更需要多个发布周期，这会带来很多潜在的人为错误。在链接的文章中，它表明2个发行版需要更改代码，而3个发行版需要数据库迁移。 我在寻找什么 当前，如果我们想记住要做的事情，可以在我们的问题管理系统中创建票证，这会造成混乱，并且还可能被管理层转移到以后的冲刺或待办事项中；或者我们可以创建一个TODO注释，它可能会完全被遗忘。 我正在寻找的方式是TODO注释可以有一个截止日期，并且，如果该截止日期已过期，我们的持续集成系统（当前将使用的未定）将拒绝该构建。 例如，如果我们重命名列，则可以为其创建初始迁移，然后创建两个TODO注释以确保创建其余的两个迁移： // TODO by v55: Create migration to move constraints to new column, remove references to old column in app // TODO by v56: Create migration to drop old column 这似乎很容易实现，但是我想知道是否已经存在类似的东西，因为我不想重新发明轮子。 其他想法 考虑到滚动部署和蓝/绿部署被认为是最佳实践，我觉得自己可能在这里遇到了XY问题，但我找不到能够减轻数据库更新麻烦的解决方案，这似乎很奇怪。如果您认为我正在完全研究错误的内容，请在评论中告诉我！就是说，我给出的数据库示例只是一个示例，我认为带有到期日期的TODO注释在其他情况下也将很有用，因此即使我正在接近这种特定情况，我还是很想回答我的问题也是实际问题。谢谢！ 编辑：我只是想这可能会有所帮助的另一种情况。如果在准备就绪时使用Feature Toggles来打开应用程序的某些部分，则必须小心清理它们，否则最终可能会出现Toggle Debt。带有截止日期的评论可能是记住这一点的好方法。

51 continuous-integration  deployment  comments  continuous-delivery 

曾经有人说过，我们应该在所有方法的前面加上 /// <summary>注释块（C＃），但没有解释原因。 我开始使用它们，发现它们使我非常恼火，因此停止使用它们，除了库和静态方法。它们体积庞大，我总是忘记更新它们。 是否有充分的理由/// <summary>在代码中使用注释块？ 我通常//一直在使用注释，这只是/// <summary>我想知道的内容。

49 c#  comments