Questions tagged «comments»

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

9
代码维护：要在代码中添加注释还是仅将其留给版本控制？
我们被要求在我们对代码进行的每个更改中添加带有开始标签，结束标签，描述，解决方案等的注释，作为修复错误/实现CR的一部分。 我担心的是，这会带来任何附加值吗？实际上，我们具有版本控制历史记录中的所有详细信息，这将有助于我们跟踪每个更改？ 但是我的领导者坚持将注释作为一种“好的”编程习惯。他们的论据之一是，当必须对CR进行范围界定/更改时，如果没有评论，那将很麻烦。 考虑到这些更改将主要在代码之间进行，是否真的有助于为我们所做的每一个更改添加注释？我们不应该把它留给版本控制吗？
12
过时的评论是都市神话吗？
我不断看到人们声称“评论趋于过时”。问题是，我认为我在整个职业生涯中可能已经看到两三个过时的评论。单独的文档中过时的信息一直在发生，但是根据我的经验，代码本身中过时的注释非常少见。 我刚刚和谁在一起很幸运吗？某些行业是否比其他行业更容易出现此问题？您是否有看到最近过时评论的具体示例？还是过时的评论更多是理论问题而不是实际问题？
38 comments  myth 
13
相关代码之前或之后的注释[关闭]
假设注释不适合（或不能加入）它所适用的行，应该在代码之前还是之后写注释？ 好吧，将来的读者无论在哪里都能最好地理解该评论的范围。换句话说，无论大多数程序员/脚本编写者在何处发表此类评论。 那么，大多数程序员/脚本编写者在何处发表评论：在其代码之前或之后？ 如果您的答案仅适用于特定语言，请指出。 而且，如果您可以引用支持您答案的公认规范或指南，那就更好了。
34 comments 
5
通常如何解析注释？
一般如何用编程语言和标记来处理注释？我正在为某些自定义标记语言编写解析器，并希望遵循最少惊喜的原则，因此我试图确定一般约定。 例如，注释是否应嵌入令牌中，从而“干扰”令牌？通常，是这样的： Sys/* comment */tem.out.println() 有效？ 另外，如果语言对新行敏感，并且注释跨越新行，是否应考虑新行？ stuff stuff /* this is comment this is still comment */more stuff 被视为 stuff stuff more stuff 要么 stuff stuff more stuff ？ 我知道几种特定的语言在做什么，我也没有在寻求意见，而是在寻找是否：是否普遍达成共识，标记对代币和新行的一般期望是什么？ 我的特定上下文是类似Wiki的标记。
31 parsing  comments 
6
写评论的初学者指南？
是否有针对初学者的明确代码编写注释指南？ 理想情况下，它将涵盖何时（不应该）使用注释以及应包含哪些注释。 这个答案： 不要评论您正在做什么，但为什么要这样做。 WHAT由干净，可读和简单的代码处理，并通过适当选择变量名称来支持它。注释显示了代码本身无法（或很难）显示的更高层次的结构。 接近，但是对于没有经验的程序员来说，这有点简洁（我认为在几个示例和极端情况的基础上进行扩展非常好）。 更新：除了这里的答案，我认为这个答案对另一个问题也非常重要。
9
您对代码注释中的句点/句号有何看法？[关闭]
已关闭。这个问题是基于观点的。它当前不接受答案。 想改善这个问题吗？更新问题，以便通过编辑此帖子以事实和引用的形式回答。 5年前关闭。 我在SO Tavern中看到了这个问题，所以我在这里发布问题。我认为这是一个有趣的问题。（当然，它不属于SO，但是我认为在这里还可以。） 您是否在代码注释中添加了句点（或者，正如OP所写，“句号”）？ 为了保持相关性，为什么？
9
注释代码的样式和建议
此问题是从Stack Overflow 迁移而来的，因为可以在Software Engineering Stack Exchange上回答。 迁移 8年前。 我想听听您在代码中编写注释的任何建议和经验。您如何以最简单，最有用的方式编写它们？注释部分代码时有什么习惯？也许一些异国情调的建议？ 我希望这个问题能收集到最有趣的建议和建议，以供大家参考。 好，我开始。 通常，/* */即使我需要注释很多行，我也不使用注释。 优点：与在单行注释中混合使用这种语法相比，代码在视觉上看起来更好。大多数IDE都具有注释选定文本的功能，并且通常使用单行语法来注释。 缺点：没有IDE，很难编辑这样的代码。 在所有已完成评论的末尾放置“点”。 例如： //Recognize wallpaper style. Here I wanted to add additional details int style = int.Parse(styleValue); //Apply style to image. Apply(style); 优点：仅在您完成的注释中放置“点”。有时您可以写时间信息，因此缺少“点”将告诉您您要返回并在此注释中添加一些其他文本。 对齐枚举中的文本，注释参数等。 例如： public enum WallpaperStyle { Fill = 100, //WallpaperStyle = "10"; TileWallpaper …
7
一个人在功能语言上应该有不同的评论吗？[关闭]
已关闭。这个问题是基于观点的。它当前不接受答案。 想改善这个问题吗？更新问题，以便通过编辑此帖子以事实和引用的形式回答。 4年前关闭。 我才刚刚开始函数式编程，我想知道注释我的代码的正确方法。 注释一个简短的函数似乎有点多余，因为名称和签名已经可以告诉您所有您需要知道的内容。注释较大的函数似乎也有些多余，因为它们通常由较小的自描述函数组成。 注释功能程序的正确方法是什么？我应该使用与迭代编程相同的方法吗？
6
如何解决嵌套评论的问题
不能嵌套注释的语言不只是一种。您对此问题有很好的解决方案吗？在C / C ++和Java中，一种解决方法是仅使用单行注释，但是注释掉较大的块将变得不可能。我正面临着这样的事情： </li><!-- <li><!-- Save --> 因此，我必须手动浏览并编辑评论。您能以多种语言建议我们应该如何处理吗？我不确定，但是python '''可能为此提供了解决方案，可以#在python中添加注释？`
23 java  c++  python  c  comments 
21
自我记录代码与 注释代码
已锁定。该问题被锁定，因为有许多离题的评论。它目前不接受新的答案或互动。 我进行了搜索，但是找不到我想要的东西，如果已经提出这个问题，请随时与我联系。 本月早些时候发表了这篇文章： http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/ 概括地说，如果您不编写注释，那么您就是一个糟糕的程序员。我个人的观点是，代码应具有描述性，并且除非注释不能自我描述，否则大多数情况下不需要注释。 在给出的例子中 // Get the extension off the image filename $pieces = explode('.', $image_name); $extension = array_pop($pieces); 作者说此代码应该给出注释，我个人认为该代码应该是描述性的函数调用： $extension = GetFileExtension($image_filename); 但是，在评论中实际上有人提出了这样的建议： http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130 作者回应说评论者是“其中的一个人”，即一个不好的程序员。 其他人对自我描述代码与评论代码有何看法？
6
为什么注释掉代码然后逐渐将其删除以跟踪我已经完成的工作和尚待完成的工作是错误的？
每当我发现需要更改我的代码的很大一部分时，要么是因为它不正确，要么是因为需要将其修改为由于其他原因而需要进行的主要体系结构更改，这通常是我要做的： 我注释掉了我怀疑可能需要更改的所有代码。我将注释掉的代码视为我的TODO列表。 我逐步查看注释掉的代码并取消注释该代码的部分，或者将它们复制粘贴到其他位置，然后根据需要对其进行编辑，或者从头开始重写此代码的部分，查看注释掉的代码以供参考。每当我认为对部分注释掉的代码完成处理后，便将其删除。 我继续进行此操作，直到看不到更多注释掉的代码为止。 我应该注意，我主要是在自己开发的个人项目上进行此操作。 但是，有人告诉我，我应该停止这样做。有人告诉我，我应该开始使用git，指代旧的提交以查看旧的代码，而不是留下注释掉的代码。有人告诉我： 注释掉代码是一个坏习惯，应该清除掉。您缺乏经验，因此无法理解。如果几年后您看到另一个喜欢注释代码的人的代码，您将开始对这个人发誓。每当我看到注释掉的代码时，我都将其完整删除，甚至根本不看它，因为通常这样的代码是完全不值钱的。您肯定不会看到在一个人的小型项目中注释掉代码的弊端。但是，如果您找到工作并保持这种习惯，那将是一种耻辱。 我想问一下我现在看不到的正在做的事情有哪些弊端吗？ 我必须说我不太热衷于仅使用git查看过去的代码。如我所说，我将注释掉的代码视为待办事项列表。虽然git会向我展示代码的外观，但无法清楚地告诉我哪些代码部分仍需要检查以及哪些部分已经完成。我担心我可能会错过一部分代码并引入错误。 为了完整起见，我想补充一点，我要引用的人是一位经验丰富的开发人员，并且是Bob叔叔的“ Clean Code”的拥护者-Bob叔叔确实批评了他的书中严厉地注释掉了代码。
6
评论写作和文档的最佳实践
此问题是从Stack Overflow 迁移而来的，因为可以在Software Engineering Stack Exchange上回答。 迁移 7年前。 如今评论比以往任何时候都容易。在Java中，有一些将注释链接到类的很好的技术，而Java IDE擅长为您创建注释外壳。像Clojure这样的语言甚至都允许您在函数代码本身中添加对函数的描述作为参数。 但是，我们仍然生活在一个时代，好开发者经常发表过时或较差的评论-我对提高评论的鲁棒性和实用性很感兴趣。 特别是在这里，我对Java / Clojure / Python感兴趣，但是答案不需要特定于语言。 是否有任何新兴技术可以验证注释并自动检测“模糊”注释（例如，带有魔术数字的注释，不完整的句子等）或不正确的注释（例如，检测拼写错误的变量等）。 更重要的是：那里是否存在公认的“评论政策”或策略？那里有很多关于如何编码的建议-但是“如何发表评论”呢？
12
要为“ false”的布尔函数参数添加正确的注释？
从一些开源项目中，我收集了以下编码样式 void someFunction(bool forget); void ourFunction() { someFunction(false /* forget */); } 我一直对false这里的含义感到怀疑。它的意思是“忘记”，还是“忘记”是指它的相应参数（如上述情况），而“假”是要否定它？ 哪种风格最常用，什么是避免歧义的最佳方法（或某些更好的方法）？
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.