Coding style 什么'；这是你最没用的评论；你见过吗？

我们都知道，注释代码是编码风格的一个重要组成部分，它可以让下一个出现的人，甚至我们自己在6个月左右的时间里都能理解我们的代码

然而，有时候一句评论并不能切中要害。我说的不是明显的笑话或发泄不满的弗罗斯顿，我说的是那些似乎在试图解释的评论，但如果做得太差，他们可能根本就不在场。太短，太晦涩，或者完全错误的评论

作为一个考顿式的故事，你能分享一些你所看到的非常糟糕的东西吗？如果它不明显，展示它所指的代码，并指出它有什么问题？什么东西应该放进去呢

另见：

---

只是典型的Comp Sci 101类型注释：

$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

---

诸如此类的事。

我发现自己以前写过这篇小文章：

//@TODO: Rewrite this, it sucks. Seriously.

---

通常情况下，这是一个好迹象，表明我已经完成了晚上的编码任务。

我曾经用一个奇怪的C编译器处理过一个项目。除非在两条语句之间插入注释，否则它在有效代码段上给出错误。因此，我将评论改为：

// Do not remove this comment else compilation will fail.

---

而且效果很好。

每一条重复代码内容的评论都是无用的。注释不应该告诉我代码的作用。如果我对编程语言不够了解，不能通过阅读代码来理解正在发生的事情，那么我根本不应该阅读这些代码。评论如

// Increase i by one
i++;

---

这些都是毫无用处的。我看到我增加了1，这就是代码所说的，我不需要任何注释！注释应该用来解释为什么要做某件事（如果它不是显而易见的），或者解释为什么这样做而不是任何其他方式（这样我就可以理解另一个程序员做出的某些设计决策，这些决策是不显而易见的）。进一步的注释有助于解释复杂的代码，在这种情况下，通过快速查看代码绝对不可能确定发生了什么（例如，有复杂的算法来计算一个数字中设置的位数；如果您不知道该代码的作用，您就没有机会猜测那里发生了什么）.

在一个巨大的VB5应用程序中

dim J
J = 0 'magic
J = J 'more magic
for J=1 to 100
...do stuff...

---

参考文献显然是。。。是的，没有这两行代码的应用程序在运行时会失败，错误代码未知。我们仍然不知道为什么

未填充的javadoc样板注释尤其无用。他们消耗了大量屏幕不动产，却没有贡献任何有用的东西。最糟糕的是，在出现这样一条评论的地方，肯定有数百条其他评论潜伏在后面

/**
 * Method declaration
 *
 *
 * @param table
 * @param row
 *
 * @throws SQLException
 */
void addTransactionDelete(Table table, Object row[]) throws SQLException {

---

IDE插入的默认注释

我参与的上一个使用WebSphere Application Developer的项目中，有很多维护开发人员和承包商，他们似乎对包含以下内容的成百上千个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.
 */

---

在你认为自己找到了一个注释良好的源文件和意识到这是另一个默认注释之间，总是有那么一瞬间，迫使你选择使用从vb6移植到vb.net的

Swarm\u WORD\u应用程序。看起来好像以前的开发人员在一个方法上放了一个注释头，然后将精确的注释复制并粘贴到他从那时起编写的每个方法上。数百种方法，每种方法都有错误的注释

当我第一次看到它时，我笑了。。。6个月后，这个笑话逐渐淡出人们的视线。
GhostDoc自己想出了一些非常有趣的笑话

/// <summary>
/// Toes the foo.
/// </summary>
/// <returns></returns>
public Foo ToFoo()

//
///用脚趾踢足球。
/// 
/// 
公共食物
我最喜欢的评论

/* our second do loop */
do {

不管是谁写的-你知道你是谁。
有一次偶然发现一个文件。数千行代码，其中大部分相当可怕。错误命名的变量、循环上的棘手条件和文件中间埋藏的注释。


   /* Hmmm. A bit tricky. */

我不相信。我是在得到22个答案后提出这个问题的，没有人指出最不可能有用的评论类型：

错误的评论

人们写多余的注释来妨碍理解代码已经够糟糕的了，但是当有人写详细的注释来解释某个东西是如何工作的，或者一开始就错了，或者在代码更改后没有更改注释（更可能的情况）就错了，这绝对是最糟糕的注释。
最糟糕的注释是对代码的功能给出错误解释的注释。
这比不发表评论更糟糕

我在代码中看到过这样的事情，注释太多了（因为代码本身就足够清晰，所以不应该有注释），而且这种情况通常发生在代码更新（重构、修改等）时，但注释不会随之更新

一个好的经验法则是：只写注释来解释代码为什么做某事，而不是解释它做什么

// remember to comment code

wtf？：D
取自我的：

// secret sauce

在清理我管理的一个项目的一些源代码的过程中，我遇到了以下评论：

然后再往下一点：

#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? 
*/

许多年前，C语言中有一个非常大的数据库引擎项目——数千行代码，其中包含短而拼写错误的变量名，并且没有注释。。。在嵌套if条件深入模块数千行之前，出现了以下注释：

//if you get here then you really f**ked

到那时，我想我们已经知道了
 类似这样：

// 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;
}

诸如此类。
肯定是代替错误处理的注释

if(some_condition){
    do_stuff();
}
else{
    //An error occurred!
}

*叹气
这是一个绝对真实的数据库示例
//if you get here then you really f**ked

// 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;
}

if(some_condition){
    do_stuff();
}
else{
    //An error occurred!
}

//' 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

try
{
...some code...
}
catch
{
// Just don't crash, it wasn't that important anyway.
}

/******************************************************************************
   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
}

  // 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 --->

//TODO: Remove this comment.

private
  //PRIVATE means PRIVATE so no comments for you
  function LoadIt(IntID: Integer): Integer;

//This causes a crash for some reason. I know the real reason but it doesn't fit on this line.