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