Use Generic Names for 3rd Party Services

One of the easiest traps for coders to fall into is naming 3rd party integrations too specifically. It comes naturally, of course. We train ourselves to adopt concise and explicit naming patterns.

So what do i mean by overly explicit names? Let's look at a couple of basic examples. If i ask someone to build a service file to integrate Stripe as our payment processing, or Sendgrid for our transactional email, i will end up with 2 files: StripeService and SendgridService. These names are too specific. Instead, what we want for file names are PaymentService and EmailService.

The reason for this is future focused. Let's say i name a file StripeService. In the future, when we change 3rd party vendors for our payment processing, the file is named wrong. This is counter productive. The entire point of a service file is to abstract 3rd party integration logic away from your codebase. By naming a service file after the vendor, we lose that abstraction. Switching vendors means that not only does the service need to be rewritten, but we have to update every place the vendor file is referenced.

When changing vendors with generic names, the service file still needs to be rewritten. But if we maintain the same functions, arguments and returns, the rest of the codebase is ignorant to the change. This is the ideal.

This brings us to a higher level lesson to be learned here: naming should be based on content or responsibility but never implementation. Naming a class after a vendor instead of the service provided is adding implementation details to the naming convention. When you think about it, this is really a form of code duplication. Thankfully, developera are good about this most of the time. It's true. Here is an analogous example to adding implementation details to a name:

# Good
total = product_cost - balance + (product_cost * tax_rate)

# Bad
product_cost_less_balance_with_taxes = product_cost - balance + (product_cost * tax_rate)

Most developers will balk at the idea of naming variables in an overly explicit way. Thankfully we have moved away from implementation details in our naming schemes. Vendor integrations seem to be the last common example of this flawed methodology.

tl;dr: Code should be named after its responsibility, not its implementation. This means you should never put vendor names in the classes that integrate them.