[jaggederest]

This is also somewhat about language choice. Languages more oriented towards natural language need less commenting. If I were writing C++ or assembler on a regular basis, I would probably be writing a lot of "what" comments.

My favorite comments are actually "what" comments, but that clarify something opaque about the code, e.g.

    const R = 6371e3;
    const φ1 = lat1 * Math.PI/180;
    const φ2 = lat2 * Math.PI/180;
    const Δφ = (lat2-lat1) * Math.PI/180;
    const Δλ = (lon2-lon1) * Math.PI/180;
    
    const a = Math.sin(Δφ/2) * Math.sin(Δφ/2) +
              Math.cos(φ1) * Math.cos(φ2) *
              Math.sin(Δλ/2) * Math.sin(Δλ/2);
    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
    
    const d = R * c;

It's extremely difficult to analyze that and say oh, obviously, that's the haversine distance formula, and the result is the distance in meters, of course. It would be slightly easier in a language with type annotations, but not a bunch easier. You add a simple

    // haversine distance formula, result is d in meters

and now you can google the wikipedia page to understand the context and history.

[dagw]

You're missing another potentially really important part in the comment. Why you chose to use the Haversine distance formula. Since you seem to be calculating the distance between two points on Earth it would be really useful to have a comment like

  // Vincenty algorithm too slow for our use case 
  // and we don't need that level of accuracy.

to make it clear that using Haversine was a conscious choice rather than the first answer you saw on the first question you looked at on Stack Overflow :)

[tharkun__]

I imagine you will use this in more than one place in the code. Why does it need a comment? Naming the function should be enough for most of it. Other languages probably aren't better at specifying the "in meters" part either, are they?

[shusaku]

The name of the function won’t necessarily reveal the algorithm used in the implementation

[LukeShu]

Yeah. I'd name the function something like `earthDistance` or `sphereDistance`, and then still have the "what" comment saying "haversine distance formula" inside of the function.

[dagw]

If I had a program where calculating distance between points on earth was important and I had an API with a function called earthDistance, then knowing that it was actually calculating the Haversine distance would be vital knowledge, since that approach is known to give quite high errors and that I should avoid using that function if I care about accuracy.

[dmurray]

Better still, I'd name it earthDistance and have that be a wrapper for another function called haversineDistance.

Then the user has the choice to call earthDistance to get the program's preferred estimate of distance, or haversineDistance if they want to be certain about the implementation. Later, perhaps you add a new distance formula and earthDistance decides which method to use as appropriate.

[tharkun__]

By all means, if the specific algorithm isn't important I would totally be onboard with you in naming it after what the purpose is instead!

Feels like the difference between inlining quicksort vs. calling quicksort() vs. calling sort(). In some situations you really are on a level where you need to know you are calling mergesort() and not quicksort() but some are fine with sort(). I doubt there are many examples of code I'd argue for inlining.

[dagw]

It's actually worse than that. Mergesort and quicksort will at least eventually give the same answer (ignoring sort stability). When it comes to numerical approximations different algorithms can all give different answers. Picking the right one is always a balance between performance, stability and accuracy and the right answer often depends on what your input looks like and how sensitive to errors you are.

[panopticon]

A function still seems appropriate even if you're not using this multiple times. Unless how you're computing the haversine distance is relevant to the surrounding code, it would be much more readable to extract it out.

[BrissyCoder]

Modern C++ is actually quite readable now imo - fairly close to C#. Has come a long way in the last 20 years.

That being said most code out there is legacy of course...

[jaggederest]

Yes, I'm probably just traumatized from trying to look at 3d engine code "back in the day" :)

[sircastor]

I just used this formula in code this last week, and I thought “hey, I recognize that!”