By Adrian Bridgett | 2019-12-22
Overview
A startup often grows to a certain size and then decides that it’s time to bring some “DevOps” expertise on board. Often this is to help scale the company - increase the velocity and ease of deployments, improve service reliability, the usual. Sometimes, however, small details make a surprising difference. One of those is naming standards.
How we got here
If I said “People are malicious and trying to make your life difficult” you wouldn’t believe me (barring the odd exception). Unless you are very unfortunate “stupidity” isn’t to blame either (even if that were the case, it wouldn’t be their fault). Normally it’s people taking the easiest path, the quickest path, failing to plan or think ahead. It can even be something normally positive such as injecting a bit of fun into work with some amusing jokes.
Naming standards - borrrrrrring
Yes, boring. But also really useful. Just the other day I was trying to find the source code for a python module called xyzlogger only to find that the git repository is called py-logging-common. Initially I searched for logger amongst the 250 git repositories, failed to find it, asked on Slack, then found it and apologised for disturbing people by asking.
The ability to discover code, services is fairly critical. What’s the server program do? Where is the source code for it? Which program services requests for auth.example.org?
Why bother - because humans
As your company grows, expecting new hires to understand oddly named projects is wildly optimistic. Amusement at finding underpants and hal9000 projects quickly turns to frustration as “in-jokes” start to divide new joiners and longer-term employees. Make life easy for your co-workers. In the same way that good design is “intuitive”, so a name should be obvious - what it represents, where to find it.
It’s also important what people themselves are called. When assigining tickets you shoudn’t have to recall that Jane Smith’s username is happy-monkey. Nor inversely that blackninja is Anna Kozmenka. A company should be open - not a secret society. Whilst it may be that developers use their personal github usernames, asking that they have their full name visible could be an acceptable compromise.
Why bother - because automation
There are many cases (server names, VPC names, etc), to list them all would be foolish, however let’s look specifically at projects. I have nothing against amusing project “code names” but to be honest I think it’s rather childish compared to having a descriptive name (some projects additionally go through multiple codenames which leaves the majority of people in a confused state (as well as missing the point of codenames)). I do think anything official should use a proper name, e.g. not superglue but config-api-backend for example. This should be used everywhere - git repository name, filesystem directories, monitoring systems, metrics, URLs (where possible), container names, package names etc.
This may sound obvious, however I’ve often seen a single project use a whole range of names in different places - a Configuration project where the code is in a config-api-backend repo, configuration in /etc/configapi/settings.yml and logs stored in /var/log/Config-API.log. People can normally cope with this to some degree, albeit with lost time and increased frustration. However, it adds a barrier to automation.
There will be times where you need to apply some tweaks - perhaps some punctuation characters aren’t allowed in some places (and so you have to replace hyphens with underscores for example). That’s fine - just be consistent.
Public-facing URLs can pose issues and that’s fine, these “friendly” names should be expected to change and not to map onto internal names. One useful trick is to have both - use the internal name for internal services, the vanity name for any external services.
Another area is usernames and email addresses. For example, if you have consistency between usernames and email addresses, then you can just email username@example.com and you know that it will reach them. A mapping of users to email addresses may work in a few isolated cases, but not all.
Speaking of email addresses, one item I’d like to highlight here is companies using first names only - this starts to become problematic very quickly. I don’t have objections to having email aliases for those lucky few that joined early - just ensure that’s it’s clear that the longer form (e.g. fred.bloggs@example.com) will work for everyone.
What should be included
The more the better. Code repository names are a good starting point as these often form the basis of everything else. Then extend to service URLs (noting that a single code repository may contain several services, but often just contains one). AWS tags, Kubernetes labels often then fall out from this quite easily (as do perhaps Vault secrets, monitoring labels). Gradually ensuring everything is consistent and discoverable.
Approach
Documentation is important as always - you need a “single source of truth”. I’d put this information on the wiki where not only can you record what the current standards are, you can explain the reasons behind them.
Over time, standards will change - that’s perfectly natural and shouldn’t be fought against. It’s unlikely that the first version will cope with all cases - especially as you don’t want to overcomplicate it. However, changes should be kept to a minimum, extending rather than replacing the standard. If old standards are still in use somewhere, leave them as a reference - but explain this - “As we expanded overseas, we added -countrycode to satellite services”. Similarly document any exceptions to the rule (naturally this is very common before any standards exist).
Configuration management helps here. For example, we manage all our GitHub details via Terraform. Not only does this bring the usual benefits (consistency, good practice applied everywhere, security, auditability), it plays a particular role in enforcing standards. If you want a new repository fine - just submit a pull request for the new repository - the “code reviewer” has a responsibility to ensure standards are being adhered to.
You could even automatically reject anything that doesn’t conform to certain basic standards (e.g. say you prefer hyphens to underscores or spaces). People often cope better with a computer telling them “No” than a person in these sort of circumstances (and it saves the reviewer time and potential concern over “annoying” a colleague).
Nomenclature
Hierarchies are useful to impose a structure, allowing people to group related work easily. For example the first part of a name is often a prefix - either a team name (mobile, backend) or project (payment, basket). When you start to reach large numbers of codebases this becomes really important, if you only have half a dozen you probably want something shorter.
A common pattern I often use is team-project[-component] (component for codebases with multiple services) - for example:
shopping-apishopping-frontendpayment-providerpayment-provider-commonpayment-provider-examplebankpayment-provider-anotherbank
I’d strongly encourage keeping names short to avoid typing fatigue as well as length limitations. You can use common abbreviations, or even adopt the Kubernetes -> k8s approach (e.g. shopping-> s6g as there are six characters missing). I like to keep everything lowercase - simple, hard to get wrong (vs Config-API or Config-Api or Config-api).
Retrofitting
It’s rare to be on a greenfield project. Most of the time this work has to be retrofitted. Rather than making invasive changes, start by fixing the new projects (and then maybe later cleaning up any particularly confusing areas). To make this process easier, fit in as far as possible with what the current practice is rather than aiming for perfection. Chances are there’s no single practice, but hopefully you can cover 80% of the cases.
Forcing people to change existing projects to fit in is probably going to cause resentment so avoid that. If it’s glaringly obvious that something isn’t fitting in with convention then often someone will “scratch the itch” and clean it up - you don’t need (or want) to pressure people.
That said, it can be useful to have some levers - and automation is such an example. For example if there is some new shiny monitoring tools that “assumes” the standards are followed, it’s not unreasonable to say “sorry, no exceptions allowed”.
Side benefits
Standards unlock other improvements. You want to alert your team to problems, just match the name. Work out why your cloud provider bill is so expensive? Not a problem - just use those handy labels on the resources. Who to ask about a service - easy. You don’t even need to be creative when coming up with repository names any longer!
Summary
Standards, and naming standards in particular, are trickier than they first appear. They can be painful to implement, however they repay investment many times over. They make it easier for both people and automation to navigate complex systems and codebases. Automation is almost impossible without them. They should be documented, enforced for new projects and extended where it makes sense.
Or perhaps play the devils advocate card and flip the argument upside down - where doesn’t it make sense to have standards?