[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.