Don’t Cry Over Missing Documentation
If we’re being honest, sometimes even the best-intentioned developers fall short when it comes to documenting their code. Given a robust API interface definition, it can still be unclear what exactly a given function call or parameter is meant to look like ( options, anyone?). So, what’s a dev to do ?
Read the source code!
Last sprint, we were working on a beta app that includes an interactive map which the user can update, adding geometries and other annotations. Like most all of our maps, it’s powered by https://github.com/mapbox/mapbox-gl-js. The drawing is powered by https://github.com/mapbox/mapbox-gl-draw. But these maps are specifically for zoning applications, and are subject to strict expectations for how the annotations will look. We aspire to design apps that empower our users to succeed painlessly, so in this instance we’ve implemented the map amendment process as a wizard. We also enforce some specific behaviors in the draw modes, for example requiring polygon labels via UI interactions. User-drawn polygons in this app represent alterations to zoning, and so logically they require labels!
To ensure created maps are legit (i.e. have labeled polygons), we hijacked some map interactions to block users who had just completed a polygon from doing anything else until that polygon was labeled. This was mostly achievable by adding checks to actions in the rendered map and map-draw components, but left open one place where the user could still finish drawing a polygon without labeling it — clicking on the map itself.
This click action was handled by mapbox-gl-draw, which owns the interactive draw map layer. In order to ensure the active, unlabeled polygon was not de-selected, it was necessary to override a specific click action to add in our label check before proceeding with normal mapbox-gl-draw behaviors. It ended up being just a few lines of code to modify a mapbox-gl-draw mode, and then use the modified mode in place of the default mode when initializing our draw-able map.
When implementing this, instead of having to rely on the mapbox-gl-draw documentation about modes — which exists, but was not clicking with my brain on Thursday at 4:30PM while trying to finish up this feature — I read through the source code, turned on my debugger, and started clicking. Pretty quickly I figured out which mode needed to be modified, and which hook on that mode needed to be intercepted and tweaked.
Debugging and reading source code for the packages and modules leveraged in our projects gives us more power when it comes to extending behaviors and fixing bugs. Documentation, when it exists, is frequently incomplete or written in such a way that I feel I’m missing out on some context or background knowledge the documenter assumed I had. When that happens, turn instead to the real source of truth — the source code. My teachers in high school always said it was best to reference primary source documents, and turns out that applies to software engineering AND social studies.
We should all try to think about our code as a primary source document, remembering that it will be revisited by interested parties in the future. So, name your variables meaningfully, and clearly, and your functions too. I will be so bold as to say: err on the side of too verbose. Take the time to rename things as classes morph and evolve. COMMENT, and then comment some more. Your teammates, or future collaborators, or just you-but-3-months-from-now, will be so happy you did.
