On Code Narrative
Tags: style, naming, python
Published: 2020-10-15 16:41:03

_**Editor's Foreword**__: This is a post from one of the developers on the Xyla Team. While not especially pertinent to mobile marketing, it is an excellent showcase of our culture and the passion of our team members, so we have elected to include it. The article also benefits from being eloquent in excess and truly delightful to read — so much so that it warrants it's own foreword. Anyways, enough from me. Enjoy!_ – [Jacob Bone](https://dev.to/jabone1)

Clarity in type and member names can constitute the difference between protracted and boring periods of familiarization when one team member needs to understand another's logic, and short but sweet explorations.

Too oft have I chosen what appears to be the cleanest and simplest name, such as `Collector`, only to soon realize that it might signify myriad different referents depending upon the specialization and mood of the reader.

## Code as Metaphor

While almost all metaphors, if extended indefinitely, break under their own weight and crush the will of the reader, they yield a few advantages when used decisively and at the core of the architecture:

- Reduced collision of terminology and identifiers, through an unambiguous diction that is an alternative to already overloaded generic terms.
- Better retention of code familiarity due to color and character imbuing often dry and repetitious syntax.
- Improved developer morale from hilarity, or, preferably good-natured humor (rather than written beatings).

## The Thing Itself

To give an example, I recently helped to create a web scraping framework to collect data from services that, while technically available to clients, was conspicuously omitted from APIs and otherwise made so laborious to access as to constitute an injurious burden on the resources of my employer.

We called the project `Raspador`, as we are fond of Spanish project names. While good for projects, a translation of a term is a code that may be opaque to someone unfamiliar with the chosen language. By contrast metaphor, if not obscure, imparts unique character using familiar words.

For `Raspador` we selected aerial combat terminology including `Pilot`, `Ordnance`, and `Maneuver` (whose only drawback is my fingers' preference of `ue` over `eu`). We could have chosen `Configuration`, `Data`, and `Stage` as generic analogies to these terms, but the latter have so many layers of previous and varied usage that the reader must first excavate their root meaning from beneath a heap of memories, then re-interpret that abstraction within the context of a scraper.

As my gentle reader already may know, a `Pilot` is present throughout a mission and is the person, i.e. user profile, involved; `Ordnance` is loaded, carried, and deployed, constituting the data specific to the scrape at; and a `Maneuver` is one flight action targeted to a specific purpose, e.g., clicking a link element to access report data.

## One Thing in Moderation

Code, as sustenance, technically requires no garnish or seasoning; and yet without it each line and each day may blend grayly into the next, fading the vision of the product. While code infused with narrative can become onerous, or simply insufferable—we did not for instance name local variables `a10` or even `warthog` (airplane models or nicknames)—it is a benefit to developers and product alike to render an implementation in terms flavorful, tasteful, and specific to keep the logic and process both on track and alive.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/23fk76n8w13ncfowdg4e.jpg)