Questions tagged «comments»

有关在代码中编写注释的问题。

4
属性的XML文档中是否需要“获取或设置..”？
我正在寻找有关C＃中XML注释的最佳实践的建议。创建属性时，预期的XML文档似乎具有以下形式： /// <summary> /// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance. /// </summary> public int ID { get; set; } 但是，因为该属性的签名已经告诉您该类的外部客户端可以进行哪些操作（在这种情况下，这两个操作都是get和set），所以我觉得注释太闲谈了，也许以下内容就足够了： /// <summary> /// ID that uniquely identifies this <see cref="User" /> instance. /// </summary> public int ID { get; set; } Microsoft使用第一种形式，因此这似乎是一个隐含约定。但是我认为由于我所说的原因，第二种更好。 我知道此问题很容易被标记为非建设性的，但是必须评论的属性数量巨大，因此我相信这个问题有权解决。 …
10
}后代码块末尾的“ //…”注释-好还是坏？[关闭]
已关闭。这个问题是基于观点的。它当前不接受答案。 想改善这个问题吗？更新问题，以便通过编辑此帖子以事实和引用的形式回答。 4年前关闭。 我经常看到这样的评论： function foo() { ... } // foo while (...) { ... } // while if (...) { ... } // if 有时甚至 if (condition) { ... } // if (condition) 我从不了解这种做法，因此也从未应用过。如果您的代码很长，以至于您需要知道结尾}是什么，那么也许您应该考虑将其拆分为单独的函数。而且，大多数开发人员工具都可以跳转到相应的括号。最后，对我来说，最后一个明显违反了DRY原则；如果您更改条件，则必须记住也要更改注释（否则可能会使维护者甚至您变得混乱）。 那么人们为什么要使用它呢？我们应该使用它，还是不好的做法？
6
是否需要在方法签名中为每个参数编写一个Javadoc注释？
我们团队中的一位开发人员认为，有必要为方法签名中的每个参数编写一个Javadoc注释。我认为这不是必要的，实际上我认为这甚至是有害的。 首先，我认为参数名称应具有描述性和自我记录性。如果您的参数的用途不是很明显，那么您可能做错了。但是，我确实知道，有时不清楚参数的用途，因此在这种情况下，应该编写一个Javadoc注释来解释该参数。 但是我认为没有必要对每个参数执行此操作。如果该参数的作用已经很明显，则javadoc注释是多余的；您只是为自己创造了额外的工作。此外，您还为需要维护代码的任何人创建了额外的工作。方法会随着时间而变化，维护注释几乎与维护代码一样重要。您有多少次看到“ X是Y导致Z原因”这样的注释，只是看到该注释已过时，实际上该方法甚至不再使用X参数？它总是发生，因为人们忘记了更新评论。我认为，误导性评论比根本没有评论更具危害性。因此存在过度注释的危险：通过创建不必要的文档，您可以 但是，我尊重团队中的另一个开发人员，并接受他也许是对的，但我错了。这就是为什么我会向其他开发人员提出您的问题：确实有必要为每个参数编写一个Javadoc注释吗？在此假设该代码是我公司内部的代码，任何外部方都不会使用。
8
在使用修订控制的商店中，“由...编辑”内联注释是否是规范？
我们商店的资深开发人员坚持认为，每当修改代码时，负责的程序员都应添加内联注释，说明他的所作所为。这些评论通常看起来像// YYYY-MM-DD <User ID> Added this IF block per bug 1234. 我们使用TFS进行版本控制，在我看来，这种注释更适合作为签入注释而不是内联噪音。TFS甚至允许您将签入与一个或多个错误关联。我们一些较旧的，经常修改的类文件看起来好像它们的LOC比率接近1：1。在我看来，这些注释使代码更难阅读并添加零值。 这是其他商店的标准做法（或至少是常见做法）吗？
5
在程序的注释中放置指向问答站点的链接可以吗？
在相当多的代码库中，您可以看到说明如下内容的注释： // Workaround for defect 'xxx', (See bug 1434594 on Sun's bugparade) 所以我有几个问题，但是它们都是相关的。 将指向SO问题的链接放在程序的注释中是否可以： // We're now mapping from the "sorted-on column" to original indices. // // There's apparently no easy way to do this in Java, so we're // re-inventing a wheel. // // (see why here, in SO …
16 comments 
16
一种不允许注释的语言会产生更具可读性的代码吗？[关闭]
很难说出这里的要求。这个问题是模棱两可，含糊，不完整，过于宽泛或夸张的，不能以当前的形式合理地回答。如需帮助澄清此问题以便可以重新打开， 请访问帮助中心。 8年前关闭。 出于好奇，我开始怀疑一种不允许注释的语言是否会产生更具可读性的代码，就像您被迫编写自我注释的代码一样。 再说一遍，您可以编写与以前一样糟糕的代码，因为您根本不在乎。但是您有什么看法？
15 comments 
9
注释if-else-clauses的好方法是什么？[关闭]
按照目前的情况，这个问题不适合我们的问答形式。我们希望答案会得到事实，参考或专业知识的支持，但是这个问题可能会引起辩论，争论，民意调查或扩展讨论。如果您认为此问题可以解决并且可以重新提出，请访问帮助中心以获取指导。 7年前关闭。 每当我用任何一种语言编写典型的if-else-construct时，我都想知道（在可读性和概述方面）向其添加注释的最佳方法是什么。特别是在评论else子句时，这些评论总是让我觉得不合时宜。假设我们有一个这样的结构（示例用PHP编写）： if ($big == true) { bigMagic(); } else { smallMagic() } 我可以这样评论： // check, what kind of magic should happen if ($big == true) { // do some big magic stuff bigMagic(); } else { // small magic is enough smallMagic() } 要么 // check, what kind …
15 comments 
7
我应该在班级文件标头中包含什么
我正在寻找有关Entity，Business Logic和Data Access类的信息丰富的类文档格式。 我从这里发现以下两种格式 格式1 ///----------------------------------------------------------------- /// Namespace: <Class Namespace> /// Class: <Class Name> /// Description: <Description> /// Author: <Author> Date: <DateTime> /// Notes: <Notes> /// Revision History: /// Name: Date: Description: ///----------------------------------------------------------------- 格式2 // =============================== // AUTHOR : // CREATE DATE : // PURPOSE : // SPECIAL NOTES: // …
4
是否有理由在签入代码中保留冲突标记？
考虑冲突标记。即： <<<<<<< branch blah blah this ======= blah blah that >>>>>>> HEAD 在促使我提出此问题的特殊情况下，负责的团队成员刚刚完成了从上游到我们分支的合并，并在某些情况下将其留为注释，以作为刚刚过去的文档解决。他将其置于编译状态，测试通过，因此它没有您想的那么糟糕。 尽管本能地，我真的对此表示反对，但是作为恶魔的拥护者，我可以理解为什么他会这样做： 因为它向其他团队开发人员强调了合并带来的变化。 因为那些在特定代码方面更精通的人然后可以解决注释所说明的问题，从而使他不必猜测。 因为上游合并是很痛苦的事情，并且可能难以证明有时间妥善解决所有问题的时机，所以需要一些半完全的FIXME通知，因此为什么不使用原始冲突作为注释来记录此问题。 我的反对是本能的，但我希望能够合理地证明其合理性，或者更明智地看待我的立场。任何人都可以给我一些例子，甚至是一些经历，其中人们与其他人在一起做得不好，和/或为什么这样做不好的原因（或者您可以扮演魔鬼的拥护者并予以支持）。 我自己直接担心的是，如果我一直在编辑有关文件之一，拉出更改，遇到真正的冲突，但也加入评论的文件，那显然会很烦人。那我确实会有一个非常混乱的文件。幸运的是，这没有发生。
6
用图作为注释注释源代码
我编写了许多（主要是c ++和javascript）代码，涉及计算几何和图形以及此类主题，因此我发现视觉图表已成为解决问题过程中不可或缺的一部分。 我现在已经确定，“哦，如果我能以某种方式将手绘图附加到一段代码上作为注释，那岂不是太棒了”，这将使我回到自己从事的工作上，数天，数周，数月之前，并且可以更快地重新获得我的算法。 作为一个视觉学习者，我觉得这几乎可以通过每种类型的编程来提高生产率，因为简单的图表可以帮助您理解和推理任何类型的非平凡数据结构。例如图表。在大学的图形理论课上，我只能真正理解我可以实际绘制的图形表示形式的图形关系。 所以... 据我所知，没有IDE可让您将图片保存为代码注释。 我的想法是，我或其他人可以提出一些合理易用的工具，该工具可以将图像转换为base64二进制字符串，然后将其插入代码中。 如果转换/插入过程可以简化，这将使图表与实际代码之间的连接更好，因此，我不再需要按时间顺序搜索笔记本。更棒的是：IDE的插件可以自动解析并显示图像。从理论的角度来看，这绝对没有困难。 我的猜测是，我将需要花费一些额外的时间才能真正弄清楚如何扩展我最喜欢的IDE并维护这些插件，因此，我对一种可以进行相同解析和解析的代码后处理器感到非常满意。渲染图像并在浏览器或其他内容中与代码并排显示。由于我是一名JavaScript程序员。 人们怎么看？有人愿意为此付费吗？我会。但是我也许还会指出，无论我本人还是同龄人中的很多人愿意为这种事情付出代价，这种事情可能成功的唯一途径就是通过开源发行。
2
内联代码注释的最佳方法是什么？
我们正在对已有20年历史的旧代码库进行一些重构，并且我正在与我的同事讨论代码中的注释格式（plsql，java）。 没有默认的注释格式，但是在大多数情况下，人们会在注释中执行以下操作： // date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment 我想要的将来和过去评论的建议格式是： // {yyyy-mm-dd}, unique_author_company_id, comment 我的同事说，我们只需要评论，并且必须将所有过去和将来的评论重新格式化为这种格式： // comment 我的论点： 我说出于维护原因，知道何时以及谁进行了更改非常重要（即使此信息在SCM中也是如此）。 该代码是有效的，因此有历史。 因为没有更改日期，如果不打开SCM工具并搜索较长的对象历史记录，就无法知道何时进行更改。 因为作者非常重要，所以改变作者比改变作者更可信 敏捷性原因，无需打开和浏览SCM工具 人们会更害怕更改某人15年前所做的事情，而不是最近创建或更改的事情。 等等 我同事的论点： 历史在SCM中 开发人员不得直接在代码中了解代码的历史记录 软件包的长度为15,000行，而且非结构化的注释使这些软件包更难以理解 您认为最好的方法是什么？还是您有更好的方法来解决此问题？
1
引入其他局部变量作为注释替换
使用其他技术上多余的局部变量来描述正在发生的事情是一种好风格吗？ 例如： bool easyUnderstandableIsTrue = (/* rather cryptic boolean expessions */); if(easyUnderstandableIsTrue) { // ... } 当涉及到技术开销时，我希望编译器能够优化此附加功能。但这是否被认为是不必要的代码膨胀？在我看来，它减少了陈旧评论的风险。
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.