我们都知道，我们的注释是代码的编码风格使我们的代码可以理解到旁边的人谁走来，甚至我们自己在6个月左右的一个重要组成部分。
然而，有时评论只是不削减芥末。 我说的不是很明显的笑话或排放frustraton，我说的是，似乎是在做一个解释的尝试，但这样做非常糟糕，他们可能也不会有意见。 评论太短 ， 太神秘 ，或者是写错了 。
作为cautonary故事，你可以分享一些你见过真的只是那么糟糕 ，如果不是很明显，显示它指的是代码，并指出这有什么错呢？ 我应该在那里，而不是已经走了吗？
也可以看看：
就在典型的计算机科学课程类型评论：
$i = 0; //set i to 0
$i++; //use sneaky trick to add 1 to i!
if ($i==$j) { // I made sure to use == rather than = here to avoid a bug
诸如此类的事情。
未填充的javadoc注释样板特别没用。 他们消耗了大量的屏幕房地产而不会造成任何有用的东西。 而最糟糕的是，其中一个这样的注释显示，数百人被肯定的背后潜伏着。
/**
* Method declaration
*
*
* @param table
* @param row
*
* @throws SQLException
*/
void addTransactionDelete(Table table, Object row[]) throws SQLException {
我发现自己以前写这个小宝石：
//@TODO: Rewrite this, it sucks. Seriously.
通常它的，我已经达到了晚上，我的编码会话结束一个好兆头。
// remember to comment code
跆拳道？ ：d
事情是这样的：
// This method takes two integer values and adds them together via the built-in
// .NET functionality. It would be possible to code the arithmetic function
// by hand, but since .NET provides it, that would be a waste of time
private int Add(int i, int j) // i is the first value, j is the second value
{
// add the numbers together using the .NET "+" operator
int z = i + j;
// return the value to the calling function
// return z;
// this code was updated to simplify the return statement, eliminating the need
// for a separate variable.
// this statement performs the add functionality using the + operator on the two
// parameter values, and then returns the result to the calling function
return i + j;
}
等等。
只是重复的代码怎么说每一个评论是无用的。 评论不应该告诉我的代码做什么。 如果我不知道编程语言不够好，明白这是怎么回事仅仅阅读的代码，我不应该阅读的代码在所有。 类似的评论
// Increase i by one
i++;
是完全无用的。 我看到，我增加了一个，那就是代码说什么，我不需要为评论！ 注释应该被用来解释为什么有些做（如果它远不是显而易见的），或者为什么有些东西是这样做的方式，而不是任何其他方式（所以我能够理解某些设计决定另一个程序员提出，是迄今为止在不明显一旦）。 再补充解释棘手的代码，它是绝对不可能确定通过在代码有一个快速浏览一下（例如，有猫腻的算法来计算一个数设置的位数发生了什么有用的，如果你不知道这个代码做什么，你有没有猜测发生的事情有）的机会。
Thread.Sleep(1000); // this will fix .NET's crappy threading implementation
我曾经在一个项目有一个奇怪的C编译器。 它的代码有效的一块给了一个错误，除非评论插入两个语句之间。 所以我改变了留言：
// Do not remove this comment else compilation will fail.
和它的工作很大。
我不相信它。 我到了这个问题后，有22个答案，没有一个人指出注释的至少可能有用的类型：
评论认为是错误的。
它的坏，以至于人们写多余的意见在理解代码的方式获得，但是当有人写了详细的注释说明一些东西是如何工作的，它要么错摆在首位，或错误的代码，而无需更改注释更改后（情景更可能），那绝对是最糟糕的一种注释。
GhostDoc出现在其自己的一些非常有趣的。
/// <summary>
/// Toes the foo.
/// </summary>
/// <returns></returns>
public Foo ToFoo()
// secret sauce
// Don't know why we have to do this
try
{
...some code...
}
catch
{
// Just don't crash, it wasn't that important anyway.
}
*叹
跨文件来过一次。 数千行代码，其中大部分是相当可怕的。 严重命名变量，在环棘手的条件语句，一个注释埋在文件的中间。
/* Hmmm. A bit tricky. */
//' OOOO oooo that smell!! Can't you smell that smell!??!??!!!!11!??/!!!!!1!!!!!!1
If Not Me.CurrentMenuItem.Parent Is Nothing Then
For Each childMenuItem As MenuItem In aMenuItem.Children
do something
Next
If Not Me.CurrentMenuItem.Parent.Parent Is Nothing Then
//'item is at least a grand child
For Each childMenuItem As MenuItem In aMenuItem.Children
For Each grandchildMenuItem As MenuItem In childMenuItem.Children
do something
Next
Next
If Not Me.CurrentMenuItem.Parent.Parent.Parent Is Nothing Then
//'item is at least a grand grand child
For Each childMenuItem As MenuItem In aMenuItem.Children
For Each grandchildMenuItem As MenuItem In childMenuItem.Children
For Each grandgrandchildMenuItem As MenuItem In grandchildMenuItem.Children
do something
Next
Next
Next
End If
End If
End If
默认的意见通过的IDE插入。
最后一个项目，我在其工作中使用的WebSphere应用开发者有足够的维护开发商和承包商谁似乎并没有被数百困扰，如果不是数千含有的这种喜欢Java类：
/**
* @author SomeUserWhoShouldKnowBetter
*
* To change this generated comment edit the template variable "typecomment":
* Window>Preferences>Java>Templates.
* To enable and disable the creation of type comments go to
* Window>Preferences>Java>Code Generation.
*/
有总是想着你居然发现一个良好的注释的源文件，并意识到之间的分裂，第二，是啊，这是另一种默认的注释，这迫使你使用SWEAR_WORD_OF_CHOICE 。
我昨天看到这个评论在C＃应用程序：
//TODO: Remove this comment.
我最喜欢的所有时间评论。
/* our second do loop */
do {
谁写的 - 你知道你是谁。
在C非常大的数据库引擎项目很多年以前 - 成千上万的短期和拼写错误的变量名行的代码，并没有意见......直到嵌套的方式深，如果条件几千行到模块下面的评论出现：
//if you get here then you really f**ked
到那个时候，我认为我们已经知道了！
在一个巨大的VB5应用程序
dim J
J = 0 'magic
J = J 'more magic
for J=1 to 100
...do stuff...
基准显然是这 ...是的，没有这两条线的应用程序在运行时失败，未知错误代码。 我们仍然不知道为什么。
从我的一个摘自博客文章 ：
在清理了一些对我管理的项目之一的源代码的过程中，我遇到了以下意见：
/*
MAB 08-05-2004: Who wrote this routine? When did they do it? Who should
I call if I have questions about it? It's worth it to have a good header
here. It should helps to set context, it should identify the author
(hero or culprit!), including contact information, so that anyone who has
questions can call or email. It's useful to have the date noted, and a
brief statement of intention. On the other hand, this isn't meant to be
busy work; it's meant to make maintenance easier--so don't go overboard.
One other good reason to put your name on it: take credit! This is your
craft
*/
然后还有更远：
#include "xxxMsg.h" // xxx messages
/*
MAB 08-05-2004: With respect to the comment above, I gathered that
from the filename. I think I need either more or less here. For one
thing, xxxMsg.h is automatically generated from the .mc file. That might
be interesting information. Another thing is that xxxMsg.h should NOT be
added to source control, because it's auto-generated. Alternatively,
don't bother with a comment at all.
*/
然后再次：
/*
MAB 08-05-2004: Defining a keyword?? This seems problemmatic [sic],
in principle if not in practice. Is this a common idiom?
*/
AHHHRRRGGHHH刚刚发现这在一些古老的代码，下注的人认为他是非常有趣
private
//PRIVATE means PRIVATE so no comments for you
function LoadIt(IntID: Integer): Integer;
最糟糕的评论是一个给人的代码做什么错误的解释。 这比没有注释更坏。
我见过这样的事情在太多的评论代码（即不应该存在，因为代码是对自己不够清晰），它主要发生在代码更新（重构，修改等）但不与它一起更新的评论。
一个好的经验法则是：只写注释解释为什么代码在做一些事情，而不是它做什么 。
绝对必须是站在原地的错误处理意见。
if(some_condition){
do_stuff();
}
else{
//An error occurred!
}
我刚刚发现这一个，写在代码注释掉的行前行：
//This causes a crash for some reason. I know the real reason but it doesn't fit on this line.
这是移植从VB6到vb.net 100K LOC应用。 看起来好像以前开发商已经把评论标题上的一个方法，然后复制并粘贴到每一个他从此写方法的确切评论。 数以百计的方法，每一个不正确的评论......
当我第一次看到它，我笑了... 6个月后，笑话穿着单薄。
这是从数据库触发器一个绝对真实的例子：
/******************************************************************************
NAME: (repeat the trigger name)
PURPOSE: To perform work as each row is inserted or updated.
REVISIONS:
Ver Date Author Description
--------- ---------- --------------- ------------------------------------
1.0 27.6.2000 1. Created this trigger.
PARAMETERS:
INPUT:
OUTPUT:
RETURNED VALUE:
CALLED BY:
CALLS:
EXAMPLE USE:
ASSUMPTIONS:
LIMITATIONS:
ALGORITHM:
NOTES:
******************************************************************************/
/** function header comments required to pass checkstyle */
我见过的两个最无助的意见...
try
{
...
}
catch
{
// TODO: something catchy
}
我张贴这一个在Daily WTF还，所以我会修剪它只是评论...
// TODO: The following if block should be reduced to one return statememt:
// return Regex.IsMatch(strTest, NAME_CHARS);
if (!Regex.IsMatch(strTest, NAME_CHARS))
return false;
else
return true;
一个我从来没有发现非常有帮助：
<!--- Lasciate ogne speranza, voi ch'intrate --->
