[lhnz]

  // Hardware acceleration should be switched off.
  // Originally we'd planned to use hardware acceleration but later
  // on in the project's life cycle we were told we needed to support older
  // versions of Foo: X and Y. This caused some bugs documented [here](#123) and [here](#234)
  // due to incomplete support of feature Z and the way that [internMethod()](#internMethod) is currently implemented.
  // @TODO: It would be better if we could switch it on or off depending on the device.
  canvas.enableHardwareAcceleration(true);

Comments should be organic and give context.

They should describe why and the high-level how, while code should describe what and the the low-level how.

That's just my opinion. This is the kind of comment I write. From time to time it becomes incorrect when a project's moving fast, but I write enough that it's very easy to validate that the use cases and code I'm talking about are real. You're meant to delete the comment immediately if it's incorrect: you can choose to help the next person understand the code or not, that's not up to me.

I think something that's very important is trying to show where a line of code or method fits in the greater scheme of the architecture of the code by linking it towards the methods that are interrelated in important ways.

Edit: You might notice I've left the comment not matching the code. This is a fact of life: somebody will change the code without updating the comment. However, because of the comment you now have a great way of sanity checking this change without having to find the original coder or test it all. Basically: it tells you what you couldn't quickly know looking at uncommented code.

[IgorPartola]

Let's look at some stylized comments I've seen over the years:

    // Add tax
    total = price + tax

Useless comment, isn't it?

    // Iterate over the order items
    for item in order:
        ...

Also useless.

    for ($i = 0; $i < count(points); $i++) {
        if (...) {
            // Break out of the loop
            $i = 1000000;
        }
    }

Not as useless as the code below it, but still pretty useless.

    def add_item(order, item):
        '''Appends item to order.

        param order : instance of <Order>
        param item : instance of <OrderItem>
        return : None
        ''''

        order.append(item)

This is a great example of a useless docstring. The developer might as well have put the code into the docstring.

    # <HACK-ALERT>
    # The code below uses an undocumented API, that nonetheless we must use in order to make the code work.
    # As per <link to StackOverflow> and <link to unresolved ticket>, this is a known issue.
    # We may be able to remove it after release X.Y where the upstream fixes it.
    
    Widget._enableDitzelMode(Widget._DITZEL_MODE_FLAG_X)

    # </HACK-ALERT>

This is not only useful, but more or less required. If you do any kind of monkey patching, please add this.

    # <DANGER>
    # The code below looks wrong, but is in fact correct. This @#$%ing API makes you say "true"
    # when you mean "false". Do not alter without reading <link to docs>.
    # Set PRODUCTION mode to ON.

    Widget.setStagingMode(true)

    # </DANGER>

This is also pretty much required, I think.

    // Make sure to use === below since foo can be null OR '' which mean different things for us:
    if (foo === null) {
        alert("Value is unknown.");
    }
    else {
        processValue(foo);
    }

I'd say also useful, but the code is going to change eventually.