Document that code!

Q: Show me a piece of code you're proud of ...

A: Here's a 10 line comment describing a single constant declaration :)

When we write code, we often tend not to properly document the core insight / intention /intuition behind optimizations. When another person (or for that matter the programmer themselves) revisits the code a while later, it seems like a non-sequitur.

The reason I'm proud of this bit of code is precisely because of that. This was an optimization for a "GeoPoint contains check for a circle with a (lat, lon) center and a radius in meters" logic coded into a geospatial index system I wrote at FB (which powers Maps/Reverse Geocoding/Local Search/Marketplace/Nearby Friends etc.).

The core insight was that instead of doing an expensive great circle / haversine distance check for each candidate, we can accept everything inside the inscribed square of the circle (which is a much cheaper Box check) and discard everything outside the superscribed square (again the cheap Box check).

This leaves us a much reduced set of candidates in between the two squares and we can do the more expensive great circle / haversine check for only those points. For a service doing billions of queries per second, this small optimization helped save a ton of computing.

I took this screenshot a year or so after writing that code, when I was revisiting that module for a feature addition. I patted the one year ago me on the back for thinking about the older / more crankier me and documenting the logic in detail. This made understanding the core intuition in the code that much easier.

That's why I cherish the comment I wrote more than the actual optimization (which was pretty nifty in its own right)!

#programminglife #geospatial #code #c++ #comment

PS: This post would be amiss without a call out to my great "co-pilots" on the Geospatial Index project. We made a great team :) #Loki4Ever Kevin Ventullo / Tina Park / Vladimir / Shannon T. / Lihan Bin