blocks|key|1168072|text|当代码不能时，经过深思熟虑的注释会得到启发。经过深思熟虑的函数和变量名称消除了大量注释的需要。如果您发现有必要对所有内容进行注释，请考虑简化代码。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1168073|entityMap^0|0^^$0|@$1|2|3|4|5|6|7|D|8|@]|9|@]|A|$]]|$1|B|3|-4|5|6|7|E|8|@]|9|@]|A|$]]]|C|$]]

Well considered comments illuminate when the code cannot. Well considered function and variable names eliminate the need for copious comments. If you find it necessary to comment everything, consider simplifying your code.

blocks|key|1165414|text|如果你曾经看过你6个月前写的代码，你会想为什么你没有更好的注释。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1165415|entityMap^0|0^^$0|@$1|2|3|4|5|6|7|D|8|@]|9|@]|A|$]]|$1|B|3|-4|5|6|7|E|8|@]|9|@]|A|$]]]|C|$]]

If you ever look at code you wrote 6 months before, you will be wondering why you did not comment better.

blocks|key|3210282|text|如果代码写得很好，使用短方法(请参阅Composed+Method模式)和meaningful+names，那么代码只需要很少的注释。只有解释“为什么”的注释才是有用的--解释“什么”的注释应该通过改进代码来替换，以至于它的作用是显而易见的。注释不应该用于编写错误代码的as+an+excuse。|type|unstyled|depth|inlineStyleRanges|entityRanges|offset|length|data|3210283|公共APIs，特别是在封闭源代码的应用程序中，可能是唯一推荐使用完整的javadoc的地方-然后你需要努力维护它们，并使它们始终准确和最新。一个误导性的或过时的评论比没有评论更糟糕。最好通过为代码编写测试并使用good+names+for+the+tests来记录代码做了什么。|3210284|Clean+Code这本书有一个关于评论的很好的章节。|3210285|entityMap|0|LINK|mutability|MUTABLE|url|http://www.ibm.com/developerworks/java/library/j-eaed4.html|1|http://tottinge.blogsome.com/meaningfulnames/|2|http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode|3|http://blog.orfjackal.net/2010/02/three-styles-of-naming-tests.html|4|https://rads.stackoverflow.com/amzn/click/com/0132350882^0|I|F|0|11|G|1|3R|C|2|0|2X|O|3|0|0|A|4|0^^$0|@$1|2|3|4|5|6|7|X|8|@]|9|@$A|Y|B|Z|1|10]|$A|11|B|12|1|13]|$A|14|B|15|1|16]]|C|$]]|$1|D|3|E|5|6|7|17|8|@]|9|@$A|18|B|19|1|1A]]|C|$]]|$1|F|3|G|5|6|7|1B|8|@]|9|@$A|1C|B|1D|1|1E]]|C|$]]|$1|H|3|-4|5|6|7|1F|8|@]|9|@]|C|$]]]|I|$J|$5|K|L|M|C|$N|O]]|P|$5|K|L|M|C|$N|Q]]|R|$5|K|L|M|C|$N|S]]|T|$5|K|L|M|C|$N|U]]|V|$5|K|L|M|C|$N|W]]]]

If the code is well written, with short methods (see <a href="http://www.ibm.com/developerworks/java/library/j-eaed4.html" rel="noreferrer">Composed Method</a> pattern) and <a href="http://tottinge.blogsome.com/meaningfulnames/" rel="noreferrer">meaningful names</a>, then the code needs very little comments. Only comments which explain the "why" are useful - the comments explaining "what" should be replaced by improving the code so much that it's obvious what it does. Comments should not be used <a href="http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode" rel="noreferrer">as an excuse</a> for writing bad code.

Public APIs, especially in closed-source apps, are perhaps the only place where thorough javadocs are recommended - and then you need to take the effort to maintain them and keep them always accurate and up-to-date. A misleading or outdated comment is worse than no comment. It's better to document what the code does by writing tests for it and using <a href="http://blog.orfjackal.net/2010/02/three-styles-of-naming-tests.html" rel="noreferrer">good names for the tests</a>.

The book <a href="https://rads.stackoverflow.com/amzn/click/com/0132350882" rel="noreferrer" rel="nofollow noreferrer">Clean Code</a> has a good chapter about comments.

blocks|key|1168149|text|评论--或者更好的是，重新编码--任何现在不明显的东西。稍后，它将是完全不明显的。你可能会想，“但那将是我”，但是如果你的思维方式(和编码方式)随着你的成长而改变，那么现在对你来说显而易见的可能以后对你就不明显了。|type|unstyled|depth|inlineStyleRanges|offset|length|style|BOLD|entityRanges|data|1168150|entityMap^0|14|1V|0^^$0|@$1|2|3|4|5|6|7|H|8|@$9|I|A|J|B|C]]|D|@]|E|$]]|$1|F|3|-4|5|6|7|K|8|@]|D|@]|E|$]]]|G|$]]

Comment -- or better yet, recode -- anything that is non-obvious now. Later it will be completely non-obvious. You might think, "but it's going to be me," but if your way of thinking (and ways of coding) changes as you grow what's obvious to you now might not be obvious to you later.

blocks|key|420098|text|单元测试之类的是最好的代码文档形式。一些测试框架写出了被测类应该做什么的规范，为人们提供了一个很好的介绍，让人们知道一段代码是如何用纯英语工作的，同时也提供了非常简洁的方法来实现测试本身。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|420099|这方面的例子有Scala的ScalaTest或RSpec。|420100|我发现，除非有问题的代码需要一些奇怪的东西，否则注释它通常是没有好处的。另外，它增加了很多开销，因为你必须维护评论……维护代码和测试已经足够了。|420101|记住，有过期注释的代码比根本没有注释更糟糕！|420102|很多时候，注释只是说代码做了什么，这是对人力的浪费。如果不是这样，你的代码可能会很糟糕，你应该重构它。|420103|只要使用测试框架即可。|420104|entityMap^0|0|0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|N|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|O|8|@]|9|@]|A|$]]|$1|D|3|E|5|6|7|P|8|@]|9|@]|A|$]]|$1|F|3|G|5|6|7|Q|8|@]|9|@]|A|$]]|$1|H|3|I|5|6|7|R|8|@]|9|@]|A|$]]|$1|J|3|K|5|6|7|S|8|@]|9|@]|A|$]]|$1|L|3|-4|5|6|7|T|8|@]|9|@]|A|$]]]|M|$]]

Unit tests and the like are the best forms of code documentation. Some testing frameworks write out a spec of what the class under test should do, giving people a great introduction to how a piece of code works in pure english while also providing very clean way to implement the tests itself.

Examples of that are Scala's ScalaTest or RSpec for Ruby.

I find that unless some weird hacky thing is required by the code in question, it is usually not beneficial to comment it. Also, it adds a lot of overhead because you have to maintain the comments... and maintaining the code and tests is already enough work. 

Remember, code with out-of-date comments is worse than no comments at all!

A lot of the time, comments just says what the code does anyway, which is a waste of human effort. And if it doesn't, your code probably sucks and you should refactor it.

Just use testing frameworks.

blocks|key|1801973|text|你读过Code+Complete了吗？推荐作为一本非常好的读物，也是一个很好的方法来弄清楚CS教授深入你的喉部的一些事情。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1801974|代码注释有两种形式：|1801975|1801976|注释解释逻辑，确保代码与意图匹配。通常，人们会编写高级伪代码，并在注释形式中使用它来填充模块将做什么的实际代码。然后，他们将注释留为通读，以便在以后的复习中使用。|ordered-list-item|1801977|注释，用于解释模块的用法。想想javadoc。你在这里的意图是让消费者理解为什么你的代码很重要。javadocs的一种用法是在Visual+Studio+Intellisense中(因为我不使用Eclipse+idk)。它在intellisense悬停时显示来自javadoc的注释。以后会变得非常方便。|1801978|1801979|当教授要求你记录代码中的所有内容时，我发现翻译成实际代码的伪代码的用法已经足够了。然而，在实践中，我没有发现许多开发人员需要它，因为通常代码足以解释自己(当简单，写得很好，不依赖于技巧，当使用描述性变量名时)。|1801980|但如果我认为有一点不清楚的话，我还是会对意图发表评论。这只是一些最佳实践。|1801981|但我绝对要说读那本书。;)|1801982|entityMap^0|0|0|0|0|0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|S|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|T|8|@]|9|@]|A|$]]|$1|D|3|-4|5|6|7|U|8|@]|9|@]|A|$]]|$1|E|3|F|5|G|7|V|8|@]|9|@]|A|$]]|$1|H|3|I|5|G|7|W|8|@]|9|@]|A|$]]|$1|J|3|-4|5|6|7|X|8|@]|9|@]|A|$]]|$1|K|3|L|5|6|7|Y|8|@]|9|@]|A|$]]|$1|M|3|N|5|6|7|Z|8|@]|9|@]|A|$]]|$1|O|3|P|5|6|7|10|8|@]|9|@]|A|$]]|$1|Q|3|-4|5|6|7|11|8|@]|9|@]|A|$]]]|R|$]]

Have you read Code Complete yet? Recommended as a very good read, and a great way to figure out some of the things CS profs drill down your throat.

Code comments come in two variety:

<ol>
<li>Comments to explain logic, making
sure that the code matches the
intent. Often people will write high
level pseudocode and will use that
in comment form to fill in the
actual code of what the module will
do. Then they leave the comments as
a read-along which can be used
during later review. </li>
<li>Comments to
explain usage of a module. Think
javadocs. Your intent here is for
the consumers to understand why your
code is important. One use of
javadocs is in the Visual Studio
Intellisense (since I don't use
Eclipse idk). It shows the comments
from the javadoc in the intellisense
hover. Becomes VERY handy later on.</li>
</ol>

When professors ask you to document everything in your code, I have found the usage of psuedocode translated to actual code to be sufficient. However, in practice I've not found that many devs need it, as usually the code is sufficient to explain itself (when simple, well written, not relying on tricks, and when using descriptive variable names).

But I still put in comments about intent if I think it's the least bit unclear. This is just a bit of best practice.

But I definitely say read that book. ;)

blocks|key|1168092|text|如果你决定开源你的个人项目，人们会感谢你的评论(除非你的评论很糟糕)。如果你偶然发现了一个非常棒的想法，并且你的个人项目变成了一项业务，那么你将雇佣更多的开发人员，你的评论也将是有价值的。如果你头部轻微受伤，那么当你回到工作岗位时，你会对你的评论心存感激。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1168093|entityMap^0|0^^$0|@$1|2|3|4|5|6|7|D|8|@]|9|@]|A|$]]|$1|B|3|-4|5|6|7|E|8|@]|9|@]|A|$]]]|C|$]]

If you ever decide to open-source your personal project, people will thank you for your comments (unless they're terrible). If you hit upon a spectacularly great idea and your personal project turns into a business, then you'll be hiring more developers, and again your comments will be valuable. If you suffer a mild head injury, then when you return to work you'll be thankful for your comments.

blocks|key|1165527|text|有些人将注释视为代码气味，这表明代码可以使用更具描述性的名称和更好的结构。他们将修复代码，使其不需要注释。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1165528|这在很多情况下都是有效的。然而，有一种类型的评论是有用的，那就是为什么要做某事。有时，修复的原因并不明显，稍后检查代码时，这些原因并不明显。注释不应该表达代码做了什么(这应该在命名中包含)或者它是如何做到的(同样，代码会告诉你这一点)，所以把你的注释保存为“为什么”。|1165529|我发现没有比单元测试更好的文档来说明一些东西是如何工作的。|1165530|entityMap^0|0|0|0^^$0|@$1|2|3|4|5|6|7|H|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|I|8|@]|9|@]|A|$]]|$1|D|3|E|5|6|7|J|8|@]|9|@]|A|$]]|$1|F|3|-4|5|6|7|K|8|@]|9|@]|A|$]]]|G|$]]

Some people treat comments as a code smell, a sign that the code could use more descriptive names and a better structure. They will fix the code so it does not need comments.

This works in a lot of cases. However one type of comment that is useful is 'why' something is being done. Sometimes fixes are made for obscure reasons that would not be obvious when reviewing the code later. The comments should not express what the code does (that should be covered by naming) or how it does that (again, the code tells you that), so save your comments for 'why'.

I find that nothing serves as better documentation as to how something works then unit tests.

blocks|key|1802000|text|每当我在做一些不是自我记录的事情时，我都会发表评论。除非我这样做，否则我会忘记我在做什么。但我更喜欢写那些显而易见的代码，以至于注释帮不了什么忙。在任何可能的情况下，代码都应该足够清晰，以便不需要数千行的注释。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1802001|不管你做什么，都不要写这样的评论...|1802002|//+add+1+to+i
%2B%2Bi;|code-block|syntax|javascript|1802003|那是噪音。实际上，有这样的评论比根本没有评论更糟糕。|1802004|entityMap^0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|M|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|N|8|@]|9|@]|A|$]]|$1|D|3|E|5|F|7|O|8|@]|9|@]|A|$G|H]]|$1|I|3|J|5|6|7|P|8|@]|9|@]|A|$]]|$1|K|3|-4|5|6|7|Q|8|@]|9|@]|A|$]]]|L|$]]

Whenever i'm doing something that isn't self-documenting, i'll put a comment. I will forget what i was doing unless i do. But i prefer to write code that's so obvious that comments don't help much. Wherever possible, the code should be clear enough that thousands of lines of comments would be unnecessary.

Whatever you do, do NOT write comments like this...

<pre><code>// add 1 to i
++i;
</code></pre>

That's noise. You're actually worse off with comments like that than with none at all.

blocks|key|3210452|text|一个核心的立场是：“如果你必须为你的代码写一个注释，你的代码就会崩溃”。与其写解释性注释，不如重构你的代码，这样注释就不那么必要了。这尤其适用于函数名(包括它们的参数)，因为它们往往被修改得最多，而注释很少被更新以匹配。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|3210453|而不是：|3210454|//+Compute+average+for+the+two+times
int+a+=+t1+%2B+(t2+-+t1)+/+2;|code-block|syntax|javascript|3210455|写|3210456|int+averageTime+=+AverageOfTimes(t1,+t2);

int+AverageOfTimes(int+t1,+int+t2)+{
++++return+t1+%2B+(t2-t1);+
}|3210457|当我阅读别人的代码时，陈旧的注释是导致WTF的主要原因之一。过度注释已经被几个作者引用为“代码气味”，包括"Clean+Code“的作者。|3210458|就我个人而言，我会为每个类写一个解释性注释(我主要是用C#和C%2B%2B编写代码)，偶尔在使用我想要引用的算法时也是如此。|3210459|entityMap^0|0|0|0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|S|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|T|8|@]|9|@]|A|$]]|$1|D|3|E|5|F|7|U|8|@]|9|@]|A|$G|H]]|$1|I|3|J|5|6|7|V|8|@]|9|@]|A|$]]|$1|K|3|L|5|F|7|W|8|@]|9|@]|A|$G|H]]|$1|M|3|N|5|6|7|X|8|@]|9|@]|A|$]]|$1|O|3|P|5|6|7|Y|8|@]|9|@]|A|$]]|$1|Q|3|-4|5|6|7|Z|8|@]|9|@]|A|$]]]|R|$]]

A hard-core stance is: "if you have to write a comment for your code, your code is broken". Rather than writing explanatory comments, refactor your code so that the comments become less necessary. This applies especially to function names (including their parameters), since they tend to be modified the most, and the comments seldom are updated to match. 

Instead of:

<pre><code>// Compute average for the two times
int a = t1 + (t2 - t1) / 2;
</code></pre>

write

<pre><code>int averageTime = AverageOfTimes(t1, t2);

int AverageOfTimes(int t1, int t2) {
 return t1 + (t2-t1); 
}
</code></pre>

Stale comments are one of the leading causes of WTF's when I'm reading other people's code.
Overcommenting has been cited as a "code smell" by several authors, including the authors of "Clean Code".

Personally, I write an explanatory comment for each class (I code in C# and C++ mostly), and occasionally when I am using an algorithm I want to refer to.

blocks|key|420956|text|老实说，如果代码是清晰的，那么就没有必要使用注释，但是当特定的逻辑在给定的特定数据(可能不是很明显)的情况下中断时，注释是最好的。留下可能发生的问题的注释是一种很好的方法，可以帮助防止由于误解预期(或具体而言不是)什么数据而导致的意外bug。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|420957|entityMap^0|0^^$0|@$1|2|3|4|5|6|7|D|8|@]|9|@]|A|$]]|$1|B|3|-4|5|6|7|E|8|@]|9|@]|A|$]]]|C|$]]

To be honest, if code is clear its not necessary, but comments are best when a specific logic breaks given certain data (which may not be obvious). Leaving comments of issues that may occur is a great way to help prevent accidental bugs due to misunderstandings of what data to expect (or specifically not).

blocks|key|419996|text|我以前和你的情况完全一样。当我刚开始的时候，我从来没有评论过任何东西，因为所有的东西都非常小，我总是知道它是如何工作的。但随着我继续扩展我的代码，所有东西都开始相互指向，我发现自己不再知道某些东西做了什么，并迷失了方向。我不得不重写很多东西，这样我就知道他们做了什么，我开始评论所有的东西，这样我就确切地知道它是如何工作的，以及将来如何使用它。你可能认为你现在知道每件事是如何工作的，但在未来，你会回过头来看一些东西并说“嗯？”最好现在评论一下，以后省事。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|419997|我评论事物的方式：|419998|总是把它添加到任何函数的顶部，这样你就知道它是做什么的。|419999|/**
+*+What+the+function+is+supposed+to+do,+a+brief+description+of+it.
+*
+*+@param+++++paramter_name+++++Object-type+++++A+description+of+it,+do+for+each+parameter.
+*
+*+@return++++Object-type+-+A+brief+description+of+what+is+being+returned.
+**/|code-block|syntax|javascript|420000|然后，在整个代码中，确保注释看起来很复杂的东西。当你运行检查时，添加一个快速的注释，比如“确保这是有效的”。对于任何较长的代码行或较大的代码块，请添加该特定部分所做工作的注释，以便以后轻松找到它。|420001|entityMap^0|0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|O|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|P|8|@]|9|@]|A|$]]|$1|D|3|E|5|6|7|Q|8|@]|9|@]|A|$]]|$1|F|3|G|5|H|7|R|8|@]|9|@]|A|$I|J]]|$1|K|3|L|5|6|7|S|8|@]|9|@]|A|$]]|$1|M|3|-4|5|6|7|T|8|@]|9|@]|A|$]]]|N|$]]

I used to be in the exact same situation as you. When I first started I never commented anything because everything was extremely small and I always knew how it worked. But as I continued to expand my code and everything started pointing to each other, I found myself not knowing what certain things did anymore and got lost. I had to rewrite a lot of things so I knew what they did again, and I started commenting everything so I knew exactly how it worked and how to use it in the future. You may think you know how everything works now, but in the future you'll look back at something and say 'HUH?' It's better to comment things now and save yourself the trouble later.

The way I comment things:

Always add this at the top of any function, so you know what it does.

<pre><code>/**
 * What the function is supposed to do, a brief description of it.
 *
 * @param paramter_name Object-type A description of it, do for each parameter.
 *
 * @return Object-type - A brief description of what is being returned.
 **/
</code></pre>

Then throughout your code make sure you comment things that look complicated. When you run checks, put a quick comment like 'make sure this is valid'. For any long lines of code or large blocks of code, add a comment of what that specific section does, to easily find it later on.

blocks|key|1165495|text|注释对于单个项目和组项目都很有用，特别是当您需要在较长一段时间内维护或增强代码时。这个场景可能不适用于学校项目，但在工作场所它绝对适用。如果你曾经不得不看过你在过去6个月里写的代码，那么它很可能是别人写的。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1165496|entityMap^0|0^^$0|@$1|2|3|4|5|6|7|D|8|@]|9|@]|A|$]]|$1|B|3|-4|5|6|7|E|8|@]|9|@]|A|$]]]|C|$]]

Commenting is useful for individual project as well as group projects especially when you will need to maintain or enhance the code over an extended period of time. This scenario may not be applicable for school projects, but in the workplace it is definitely applicable. If you have ever had to look at code that you wrote 6 months in the past then it might as well have been written by somebody else.

blocks|key|3210479|text|我发现--正如每个人都会告诉您的那样--如果您在几个月后重新开始编写代码，您将忘记一切。也就是说，除了像//+ew..+hacked+because+X-beyond-my-control+doesn't+do+Y+correctly这样的注释，我几乎不注释我自己的代码。但这是因为代码本身写得非常干净，非常容易阅读。例如，所有变量和函数名称都是完全描述性的。我不使用缩写，除了明显的很长的单词，比如'info‘。所有的功能都非常简短。如果可能，所有函数都做一件事。如果可能，应避免嵌套。逻辑上相关的函数通过类或模块进行分组。|type|unstyled|depth|inlineStyleRanges|offset|length|style|CODE|entityRanges|data|3210480|当我阅读别人的代码时，我不会阅读注释。我读过代码。清晰和写得很好的代码和意大利面条之间的区别比任何注释都重要得多。通常我并不关心他们的意图是什么，我想要更改代码。要做到这一点，它需要组织得很好。所以这些评论是无关紧要的。但也许这只是我一个人。|3210481|entityMap^0|1G|1T|0|0^^$0|@$1|2|3|4|5|6|7|J|8|@$9|K|A|L|B|C]]|D|@]|E|$]]|$1|F|3|G|5|6|7|M|8|@]|D|@]|E|$]]|$1|H|3|-4|5|6|7|N|8|@]|D|@]|E|$]]]|I|$]]

I have found that--as everyone will tell you--if you are coming back to code after several months you will have forgotten everything. That said, I hardly comment my own code except for comments like <code>// ew.. hacked because X-beyond-my-control doesn't do Y correctly</code>. But this is because the code itself is written very cleanly and is very easy to read. For instance, all variable and function names are completely descriptive. I don't use abbreviations except for rather long words which are obvious such as 'info'. All functions are extremely brief. All functions do one thing if possible. Nesting is avoided if possible. Logically related functions are grouped via classes or modules.

When I read other people's code, I don't read the comments. I read the code. And the difference between clear and well written code and spaghetti is far more important than any comments. Usually I don't care what their intent is/was; I want to change the code. And to do that it easily it needs to be well organized. So the comments are peripheral. But perhaps this is just me.

blocks|key|1802099|text|从技术上讲，代码是完全自我文档化的。我喜欢评论任何不明显或特别复杂的东西。我倾向于至少有一个类的摘要，也许每个成员都有一个简短的简介。当你必须在一个非常大和复杂的方法上编写大量文档时，这通常是一个好兆头，表明它需要进行重构。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1802100|foreach(var+a+in+b.Items)+//Enumerate+the+items+in+"b"
{
++++if(a.FirstName+==+"Jones")+//See+if+first+name+is+Jones
....+|code-block|syntax|javascript|1802101|你想要的东西在上述中间，而不是任何评论。|1802102|entityMap^0|0|0|0^^$0|@$1|2|3|4|5|6|7|K|8|@]|9|@]|A|$]]|$1|B|3|C|5|D|7|L|8|@]|9|@]|A|$E|F]]|$1|G|3|H|5|6|7|M|8|@]|9|@]|A|$]]|$1|I|3|-4|5|6|7|N|8|@]|9|@]|A|$]]]|J|$]]

Technically speaking the code is perfectly self documenting. I like to comment anything that is non-obvious or especially complex. I tend to like to have at minimum summary on a class, and maybe a short blurb for each member. When you have to write a huge amount of doc on a very large and complex method that is usually a good sign that it needs to be looked at for a refactor.

<pre><code>foreach(var a in b.Items) //Enumerate the items in "b"
{
 if(a.FirstName == "Jones") //See if first name is Jones
.... 
</code></pre>

You want something in the middle of the above and no commenting whatsoever.

blocks|key|420208|text|评论总是有用的！我不认为评论是浪费时间！它可以帮助其他开发人员理解你的代码，当你几个月没有在项目上工作的时候，它也会帮助你。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|420209|entityMap^0|0^^$0|@$1|2|3|4|5|6|7|D|8|@]|9|@]|A|$]]|$1|B|3|-4|5|6|7|E|8|@]|9|@]|A|$]]]|C|$]]

commenting is always useful!And I dont thik that commenting is a waste of time!It helps other developeres understand your code and it helps you when you haven't work on a project for months.

blocks|key|420973|text|大学软件课程经常促使人们进行过多的评论，以此来迫使学生三思而后行。几年前，当我在批改本科生的课程作业时，一条令人讨厌的经验法则建议每5-10行就有一条评论。我认为大多数Java课程都告诉您将方法限制在30行左右，因此一个函数中的大量注释是您应该拆分它的标志。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|420974|我个人的偏好是将注释限制为记录函数用途/输入/输出和数据结构。否则，评论应该局限于需要特别注意的东西(例如，看起来不合适的东西，可能是bug，乍一看)。|420975|entityMap^0|0|0^^$0|@$1|2|3|4|5|6|7|F|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|G|8|@]|9|@]|A|$]]|$1|D|3|-4|5|6|7|H|8|@]|9|@]|A|$]]]|E|$]]

University software courses often push people towards excessive commenting as a way of forcing students to think twice about what they have typed. A nasty rule-of-thumb that was put my way when I was marking undergrad coursework a few years ago suggested a comment every 5-10 lines. Think most Java courses tell you to limit methods to circa 30 lines, so lots of comments within a function is a sign you should break it up.

My personal preference is to limit comments to documenting function purpose/inputs/outputs and data structures. Otherwise comments ought to be limited to things that require particular attention (eg things that looks out of place, perhaps bugs, at first glance).

blocks|key|420252|text|第一个注释是变量和方法名。在选择它们时要特别注意。如果你能想出一个更好的名字，请不要犹豫，重新命名它们。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|420253|一致性和约定也有帮助。尽量避免使用NumberOfStuff，ThingCount，FooSize，总是使用相同的形式，可能是与语言一致的形式(它是否有Array.length或Vector.size)。总是用相似的名字来命名相似的东西。|420254|“代码从不说谎，注释有时会”。总有一天，有人会修改代码，而不是相关的注释。最好花更多的时间编写带有一些巧妙注释的自解释代码，而不是拆分代码，然后用大量注释来解释事情。|420255|entityMap^0|0|0|0^^$0|@$1|2|3|4|5|6|7|H|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|I|8|@]|9|@]|A|$]]|$1|D|3|E|5|6|7|J|8|@]|9|@]|A|$]]|$1|F|3|-4|5|6|7|K|8|@]|9|@]|A|$]]]|G|$]]

The first comments are the variables and methods names. A lot of attention shall be paid to choose them. Do not hesitate to rename them if you can think of a better name. 

Consistency and convention also help. Try to avoid NumberOfStuff, ThingCount, FooSize, always use the same form, possibly something in line with the language (does it have Array.length, or Vector.size). Always name similar things with similar names. 

"Code never lies. Comments sometimes do". One day or the other, someone will modify the code and not the associated comment. Better spenf more time writing self-explanatory code complemented with some clever comment, than splitting out code and then explaining things with a lot of comments.

blocks|key|1802339|text|规则#1注释应该指出为什么不是“什么”(代码已经告诉你“发生了什么”)。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1802340|规则#2在写完评论后-重写你的代码，让它读起来像评论一样(然后删除评论)|1802341|entityMap^0|0|0^^$0|@$1|2|3|4|5|6|7|F|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|G|8|@]|9|@]|A|$]]|$1|D|3|-4|5|6|7|H|8|@]|9|@]|A|$]]]|E|$]]

Rule #1
Comments should indicate WHY not 'what' (the code already tells you 'what' is happening)

Rule #2
After writing the comment - rewrite your code to read like the comment (then remove the comment)

blocks|key|1165803|text|虽然好的变量和函数名等可能会减少对注释的需求，但任何足够复杂的程序仅仅通过查看代码就很难理解，无论它是如何仔细编写的。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1165804|一般来说，代码的主体越大，预计使用的时间越长，编写详细注释就越重要。对于教师来说，要求详细的注释是完全合理的，因为他们不想花费大量的时间来试图理解不同学生的大量代码，但您不必在课堂之外保持相同的标准。|1165805|关于注释函数&类之类的，我发现只有最琐碎的函数是自解释的，以至于注释不会为读者节省一些时间。此外，当您为Java或Curl等语言使用智能IDE时，编写格式正确的文档注释将允许开发人员只需将鼠标悬停在调用签名上，即可查看函数和方法的文档。在使用大型系统时，这可以为您节省大量时间。|1165806|entityMap^0|0|0|0^^$0|@$1|2|3|4|5|6|7|H|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|I|8|@]|9|@]|A|$]]|$1|D|3|E|5|6|7|J|8|@]|9|@]|A|$]]|$1|F|3|-4|5|6|7|K|8|@]|9|@]|A|$]]]|G|$]]

While good variable and function names etc. may lessen the need for comments, any sufficiently complex program is going to be hard to understand merely by looking at the code alone, no matter how carefully it was written.

In general, the larger the body of code and the longer you expect it to be in use, the more important it will be to write detailed comments. It is perfectly reasonable for teachers to demand detailed comments because they don't want to have to spend a lot of time trying to understand large amounts of code from different students, but you don't necessarily have to maintain that same standard outside the classroom.

Regarding commenting functions &amp; classes and the like, I find that only the most trivial functions are so self explanatory that a comment won't save the reader some time. Also, when you are using a smart IDE for a language such as Java or Curl writing properly formatted documentation comments will allow developers to see documentation for functions and methods simply by hovering over a call signature. This can save you a lot of time when working with large systems.

As a student in computer engineering I have been pressured to type up very detailed comments for everything I do. I can see this being very useful for group projects or in the work place but when you work on your own projects do you spend as much time commenting? 

As a personal project I am working on grows more and more complicated I sometimes feel as though I should be commenting more but I also feel as though it's a waste of time since I will probably be the only one working on it. Is it worth the time and cluttered code?

Thoughts? 

EDIT: This has given me a lot to think about. Thanks for all your input! I never expected this large of a response.

Commenting practices?

翻译质量差，导致语言生硬或混乱。

没有提供实际的解决方法或示例。

解答不清晰，无法理解或解决问题。

页面排版不美观，阅读体验差。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

作为一名计算机工程专业的学生，我不得不为我所做的每一件事输入非常详细的评论。我可以看到这对团队项目或工作场所非常有用，但是当你在自己的项目上工作时，你会花同样多的时间来评论吗？随着我的个人项目变得越来越复杂，我有时觉得我应该更多地评论，但我也觉得这是浪费时间，因为我可能是唯一一个在做它的人。这值得花费时间和杂乱的代码吗？有什么想法？编辑:这给了我很多思考。感谢您的所有投入！我从来没想过会有这么大的

问评论实践？
EN

回答 20

Stack Overflow用户

Stack Overflow用户

Stack Overflow用户

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问评论实践？EN

回答 20

Stack Overflow用户

Stack Overflow用户

Stack Overflow用户

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问评论实践？
EN