[nishs]

Exactly.

Here is another example where a comment can help.

  // Do does x, y, and z, in that order.
  func Do(x, y, z func()) { 
      x()
      z()
      y() 
  }

Sometimes, as here, the comment correctly describes what the code should do. But the implementation does not agree with the comment. Relying on the comment, a developer can confidently fix the bug, or, at least, notice a discrepancy between the intentions, as described by the comments, and reality, as implemented by the lines of code. This is particularly important in complex code. Think: HTTP keep-alive handling, in which many factors, with varying priorities, have to be taken into account (e.g. client hint in the request header, current server load, overall server configuration, per handler configuration).

[turdprincess]

It’s also plausible that the function used to do x,y,z in that order, but then a new requirement came to do z before y. The code was changed, maybe a test was even added, but the comment was never fixed.

That’s the problem with comments (and all documentation really) - it gets stale and has no guarantee of being correct.

A better way is to write a test which would break if the order of x,y,z was wrongly changed. This way the order is guaranteed to stay correct forever, regardless of any comments.

[nishs]

I agree with your points regarding writing a test. It is one of the best ways, and the right way, to handle the issue.

That said, I think my toy example wasn't the best way to show some of the points I was getting at. Consider a real example, such as this function from file src/net/http/transport.go in the Go source:

        // rewindBody returns a new request with the body rewound.
        // It returns req unmodified if the body does not need rewinding.
        // rewindBody takes care of closing req.Body when appropriate
        // (in all cases except when rewindBody returns req unmodified).
        func rewindBody(req *Request) (rewound *Request, err error) {
                if req.Body == nil || req.Body == NoBody || (!req.Body.(*readTrackingBody).didRead && !req.Body.(*readTrackingBody).didClose) {
                        return req, nil // nothing to rewind
                }
                if !req.Body.(*readTrackingBody).didClose {
                        req.closeBody()
                }
                if req.GetBody == nil {
                        return nil, errCannotRewind
                }
                body, err := req.GetBody()
                if err != nil {
                        return nil, err
                }
                newReq := *req
                newReq.Body = &readTrackingBody{ReadCloser: body}
                return &newReq, nil
        }

When you work with code in or around this function, the existence of the comments tell you what the function guarantees, for example, regarding the closing of the request body. If at some point, there is a bug, it is more likely to be noticed because of the discrepancy between the intentions in the comment and the implementation in the code. Without the descriptive comment, an unfamiliar developer working on this code will likely not be able to tell if something is off in the function's implementation.

Also, as a user of code, it's nice to first know descriptively what guarantees a complex internal function promises from its comment. Then, if necessary, be able to verify those guarantees by reading the function body.

Of course, in an ideal scenario, a unit test is the best way to address things. But this this is a 22 line function unexported function in at 2900 line file, and sadly it appears this function isn't unit tested.

So, given how things are in practice, I argue that the presence of a comment, like here, can help with correctness of code.