你见过的最不实用的评论是什么？

We all know that commenting our code is an important part of coding style for making our code understandable to the next person who comes along, or even ourselves in 6 months or so.

我们都知道,对我们的代码进行评论是编码风格的一个重要部分,使我们的代码可以理解为下一个人,或者甚至是我们在6个月左右的时间。

However, sometimes a comment just doesn't cut the mustard. I'm not talking about obvious jokes or vented frustraton, I'm talking about comments that appear to be making an attempt at explanation, but do it so poorly they might as well not be there. Comments that are too short, are too cryptic, or are just plain wrong.

然而,有时评论不会削减芥末。我不是在谈论明显的笑话或通风挫折,我说的是那些似乎试图解释的评论,但这样做很差,他们可能不会在那里。评论太短,太神秘,或者只是完全错误。

As a cautonary tale, could you share something you've seen that was really just that bad, and if it's not obvious, show the code it was referring to and point out what's wrong with it? What should have gone in there instead?

作为一个故事,你能否分享一些你曾经看过的那些真的那么糟糕的东西,如果不是很明显的话,请展示它所指的代码并指出它有什么问题?应该去哪里呢?

101 个解决方案

#1

112

Just the typical Comp Sci 101 type comments:

只是典型的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

That sort of thing.

诸如此类的事情。

#2

Unfilled javadoc boilerplate comments are particularly useless. They consume a lot of screen real estate without contributing anything useful. And the worst part is that where one such comment appears, hundreds of others are surely lurking behind.

未填充的javadoc样板评论特别无用。他们消耗了大量的屏幕空间而没有贡献任何有用的东西。最糟糕的是,出现一个这样的评论,其他数百个肯定会潜伏。

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

#3

I've found myself writing this little gem before:

我之前发现自己写了这个小宝石:

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

Usually it's a good sign that I've reached the end of my coding session for the night.

通常这是一个好兆头,我已经到了我的编码会议结束了一夜。

#4

// remember to comment code

wtf? :D

#5

Something like this:

像这样的东西:

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

And so on.

等等。

#6

Every comment that just repeats what the code says is useless. Comments should not tell me what the code does. If I don't know the programming language well enough, to understand what's going on by just reading the code, I should not be reading that code at all. Comments like

每一条只重复代码所说的评论都是无用的。评论不应该告诉我代码的作用。如果我不太了解编程语言,只要阅读代码就能理解正在发生的事情,我根本不应该阅读那些代码。评论如

// Increase i by one
i++;

are completely useless. I see that i is increased by one, that is what the code says, I don't need a comment for that! Comments should be used to explain why something is done (in case it is far from being obvious) or why something is done that way and not any other way (so I can understand certain design decisions another programmer made that are by far not obvious at once). Further comments are useful to explain tricky code, where it is absolutely not possible to determine what's going on by having a quick look at the code (e.g. there are tricky algorithms to count the number of bits set in a number; if you don't know what this code does, you have no chance of guessing what goes on there).

完全没用。我看到我增加了一个,这就是代码所说的,我不需要对此进行评论!应该使用注释来解释为什么要做某事(如果它远非显而易见)或为什么以某种方式完成某些事情而不是任何其他方式(因此我可以理解另一个程序员所做的某些设计决策,这些决策到目前为止并不明显)一旦)。进一步的注释对于解释棘手的代码非常有用,因为绝对不可能通过快速查看代码来确定发生了什么(例如,有一些棘手的算法来计算数字中设置的位数;如果不是知道这个代码做了什么,你没有机会猜测那里发生了什么。

#7

Thread.Sleep(1000); // this will fix .NET's crappy threading implementation

#8

I once worked on a project with a strange C compiler. It gave an error on a valid piece of code unless a comment was inserted between two statements. So I changed the comment to:

我曾经在一个带有奇怪的C编译器的项目上工作过。除非在两个语句之间插入注释,否则它会对有效代码进行错误处理。所以我把评论改为:

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

And it worked great.

它运作得很好。

#9

I don't believe it. I came into this question after it had 22 answers, and no one pointed out the least possibly useful type of comment:

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

comments that are wrong.

评论错了。

It's bad enough that people write superfluous comments that get in the way of understanding code, but when someone writes a detailed comment explaining how something works, and it's either wrong in the first place, or wrong after the code was changed without changing the comment (much more likely scenario), that is definitely the worst kind of comment.

人们编写多余的评论会妨碍对代码的理解,但是当有人写出详细的评论来解释某些内容是如何工作的时候,这可能是错误的,并且首先是错误的,或者在更改代码而不更改注释后更改错误(更可能的情况),这绝对是最糟糕的评论。

#10

GhostDoc comes up with some pretty interesting ones on its own.

GhostDoc自己提出了一些非常有趣的。

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

#11

// secret sauce

#12

// Don't know why we have to do this

#13

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

*sigh

#14

Came across a file once. Thousands of lines of code, most of it quite horrendous. Badly named variables, tricky conditionals on loops and one comment buried in the middle of the file.

遇到过一次文件。成千上万的代码行,其中大部分代码都非常可怕。错误命名的变量,循环上的棘手条件和埋在文件中间的一条注释。


   /* Hmmm. A bit tricky. */

#15

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

#16

Default comments inserted by IDEs.

IDE插入的默认注释。

The last project I worked on which used WebSphere Application Developer had plenty of maintenance developers and contractors who didn't seem to be bothered by the hundreds, if not thousands of Java classes which contained the likes of this:

我使用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.
 */

There was always that split-second between thinking you'd actually found a well-commented source file and realising that, yup, it's another default comment, which forced you to use SWEAR_WORD_OF_CHOICE.

在认为你实际上找到一个评论良好的源文件并意识到这一点之间总是存在分秒,是的,这是另一个默认注释,它迫使你使用SWEAR_WORD_OF_CHOICE。

#17

I saw this comment yesterday in a C# app:

我昨天在C#应用程序中看到了这条评论:

//TODO: Remove this comment.

#18

My favorite all-time comment.

我最喜欢的评论。

/* our second do loop */
do {

Whoever wrote it - you know who you are.

谁写了 - 你知道你是谁。

#19

a very large database engine project in C many many years ago - thousands of lines of code with short and misspelled variable names, and no comments... until way deep in nested if-conditions several thousands of lines into the module the following comment appeared:

许多年前C中的一个非常大的数据库引擎项目 - 数千行代码,包含短变量和拼写错误的变量名称,没有注释......直到嵌套if条件深入到模块中的数千行,出现以下注释:

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

by that time, i think we knew that already!

到那个时候,我想我们已经知道了!

#20

In a huge VB5 application

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

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

The reference is obviously THIS ... and yes, the application without those two lines fails at runtime with an unknown error code. We still don't know why.

引用显然是这个......是的,没有这两行的应用程序在运行时因未知错误代码而失败。我们仍然不知道为什么。

#21

Taken from one of my blog posts:

取自我的一篇博文:

In the process of cleaning up some of the source code for one of the projects I manage, I came across the following comments:

在清理我管理的一个项目的一些源代码的过程中,我发现了以下注释:

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

and then a little further down:

然后再往下走一点:

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

and then yet again:

再一次:

/*
   MAB 08-05-2004: Defining a keyword?? This seems problemmatic [sic],
   in principle if not in practice. Is this a common idiom? 
*/

#22

AHHHRRRGGHHH Just found this in some ancient code, bet the guy thought he was pretty funny

AHHHRRRGGHHH刚刚在一些古老的代码中找到了这个,打赌这家伙认为他很有趣

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

#23

The worst comment is one that gives a wrong explanation of what the code does. That is worse than no comment at all.

最糟糕的评论是对代码的作用给出了错误的解释。这比没有评论更糟糕。

I've seen this kind of thing in code with way too many comments (that shouldn't be there because the code is clear enough on its own), and it happens mostly when the code is updated (refactored, modified, etc.) but the comments aren't updated along with it.

我在代码中看到过这样的东西有太多的注释(不应该存在因为代码本身足够清晰),并且它主要发生在代码更新(重构,修改等)时但评论不随其更新。

A good rule of thumb is: only write comments to explain why code is doing something, not what it does.

一个好的经验法则是:只写出注释来解释为什么代码在做什么,而不是它做什么。

#24

Would definitely have to be comments that stand in place of error handling.

绝对必须是代替错误处理的注释。

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

#25

I just found this one, written on the line before a commented-out line of code:

我刚发现这个,在注释掉的代码行之前写在行上:

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

#26

100k LOC application that was ported from vb6 to vb.net. It looks as though a previous developer had put a comment header on one method and then copied and pasted the exact comment onto every method he wrote from then on. Hundreds of methods and each one incorrectly commented...

从vb6移植到vb.net的100k LOC应用程序。看起来好像以前的开发人员在一个方法上放了一个注释标题,然后将确切的注释复制并粘贴到他从那时起编写的每个方法上。数百种方法,每一种都错误评论......

When i first saw it i laughed... 6 months later the joke is wearing thin.

当我第一次看到它时,我笑了...... 6个月后这个笑话很薄。

#27

This is an absolutely real example from a database trigger:

这是数据库触发器的绝对真实示例:

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

#28

/** function header comments required to pass checkstyle */

#29

The two most unhelpful comments I've ever seen...

我见过的两个最无益的评论......

try
{
  ...
}
catch
{
  // TODO: something catchy
}

I posted this one at the Daily WTF also, so I'll trim it to just the comment...

我也在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;

#30

One I've never found very helpful:

一个我从未发现过非常有帮助的:

<!--- Lasciate ogne speranza, voi ch'intrate --->

#1

112