I’ve been thinking more based on the analogy from my previous post and had some more ideas about how the design of a city nicely illuminates the design of a software project. In a city, there are differences between how you optimize design for locals and for visitors. For locals, you want specialized shortcuts, quickly digestible localisms, and other efficiencies that leverage familiarity. When designing for visitors, you want ease of use. Broadly familiar terms on signs, clear and easy to navigate streets, etc. Further, within a city, different neighborhoods are going to have different balances between local and visitor audiences.

Similarly, areas within a codebase will have different needs given the primary audience that will experience them. In some places, you’ll want hyper specialized and nuanced functions and constructs, while in others, it may be worth some sacrifice in performance or DRYness for readability and ease of understanding (this is subtly but importantly different from clarity). It’s important to realize that this balance will not be consistent across the entire codebase either.

What’s possibly most important to understand, in my mind, about where a particular piece of code falls on the visitor-resident spectrum is how your organization works with respect to that piece of code, rather than anything specific about the actual functionality of the code. Is this code a handful of people are interfacing with every week or 2 (residents), or is this something a large number of people are going to work with once or twice a quarter (visitors)?

Consider 2 sets of functions. On the one hand,
apply_sku_adjustments(cart, customer)
On the other,
apply_taxes(line_items, jurisdictions)
apply_quantity_discounts(line_items)

Neither of these is wrong in an absolute sense, but they are optimized for different audiences. The first requires much more specialized knowledge to make sense of (what’s a sku, why are we adjusting them, what kind of adjustments are they, how do they relate to a cart, what do they have to do with the customer). The second communicates at the abstraction boundary in terms and concepts most people can understand right away. The first may well suit residents better, while the second is better for visitors.

When writing code like when designing a city, it’s important to ask yourself, who will see this, and how can I help them understand it quickly and clearly. These are not independent concerns, but rather the later is contingent on the former.