Call a spade a spade (en); Het beestje bij zijn naam noemen (nl); Называтьвещисвоимиименами (ru).
Hello, my name is Paul. I’m a backend developer here at aFrogleap. I do this job for 5+ years now. And, probably, have seen most of the history of this company. In this article I'm going to take you on a tour into the world of naming conventions. This is how our story began...
Wildlife of Famous Russians
I took cloud/backend responsibilities from someone else. And there was not so much to take control over: couple of scripts running on sole server. No naming conventions, no auditing software. Back then computer clouds just started to appear like 'mushrooms after a summer rain'. Everyone was thinking “old-school”: have just one Server and install all software there and pray it won’t “rain”. Clouds – fail. Instances – can become unreachable; some hardware failure may occur at any given moment in time.
With this old-school understanding, someone named our main server a “WorkHorse” (obfuscated for security reasons).
As we frogs continued to leap ahead with knowledge and professionalism, we started to have an urge for a separate testing environment. The one to test changes. And the same one that could have breaking and incomplete changes. So, we named it “WorkHorsie”. Some time passed and there spawned a need to separate one of the “micro-services” into its own environment. High-load is here – don’t put all your eggs into the same basket. The name of this server became “Lenin”, as Lenin is Always Alive. And so the naming convention became: Name all new servers with Soviet famous people’ names.
And then, another frog leap later, we started to get more clients, more projects, more teammates… And thus, more servers! Things that might be easy to understand for one, became difficult to others. Different cultural backgrounds made an existing naming convention into a chaos.
The problem is here. Things are getting out of hands. You receive alarms and notifications with weird letters that look like gibberish. And first thing you have to do is to figure out what exactly needs your attention. Would you like to get some system in place that will easily tell where to apply your care? Will it save time?
With this article I will try to create order in this chaos to sort out how we name our data at aFrogleap. I will mention thoughts that we used to come to this current convention. These conventions are related to our Backend infrastructure, same principles can be applied to other tools and disciplines. This is not a definitive guide, some ideas may or may not suit your needs. And yes, as everything in this world, conventions are constantly changing. Sometimes crucial refactoring, but mostly in minor details. Apply responsively.
Flavors of Order to our Chaos
Name it right – and everyone will understand it. Well, not everyone, and, maybe, not from the first glimpse. But simple patterns are easy to get. Databases, Servers, Networks, Accounting software, Dropbox folders, Distributions and Environments. You can “program” your patterns on all the levels of your tool chain, so if one system fails – you have a backup system in place. If one system becomes obsolete – just remove it and plug a different one in the same place. Clean and easy.
The benefits of conventions, in general:
- Information compression
- Formalization of expectations / Searchability
- Collision avoidance
- Professional appearance
You start with outlining what you currently have. Just some overall abstracts.
We work on Top of Amazon Web Services (AWS). “AWS is a secure cloud services platform, offering compute power, database storage, content delivery and other functionality to help businesses scale and grow”, - quote from their website. They have their own conventions. EC2 instances are prefixed with “i-”; AMIs are prefixed with “ami-”; VPCs, subnets, ACLs, Security groups. Everything. And it followed by some random characters. Add just a little bit of structure to this and it becomes an 'easy-peasy' thing to parse, catalog, audit and name.
Then you start asking questions.
Based on current flow within the company these are the questions I’ve started asking:
- Are we the only “client”? Do we have multiple clients?
- Do these multiple clients have one and only project that they need? Do the clients come back to us with many Interesting ideas?
- Do we deploy to “the only” production environment? Or do we have multiple stages of continuous testing and deployment?
- Do we have one application to do all it needs to do? Or you are moving to micro-services infrastructure? What about different types of your microservice-based applications? What are the primary purpose of these applications?
- Are we developing for one platform? Do we develop for and support many or all of them? What are the languages and frameworks we use?
- What are our limits?
- What about future extend-ability?
And then you start answering them.
In our case we do have multiple clients. aFrogleap, Oxyma, Red Cross to name a few. Mentioning relation to a certain client simplifies things.
Our clients come back to us. With more ideas and we create awesome engaging experiences. We love our clients. We’ve built a lot of backends to applications like RedCross Nederland AED, aFL Poke-a-Frog, Poof It’s Gone.
We also have multiple stages of deployment. The environments should have their stages mentioned. You can also dispose of your older unneeded environments based on this pattern. Standard stages are Integration, Staging, Production.
In production we have internet-facing environment as well as a couple of worker environments. Sometimes, even, multiple of the same kind of environments with different purposes. Not to mention, databases and storage locations. Web, Worker, CMS, API, MongoDB, MySQL, Docker. It is almost a Zoo now. As you can see, we are still settling with the standard for this area.
Some systems that you use, have their own limits. Get a hold of the limitations and act on that. For example, difference of file-systems of different kind. Windows vs Linux/Unix-like vs MacOS. Some of them are Case In-Sensitive, some of them are. And all of them have something in common – (dashed word separation) Use that to your advantage. All the guides recommend avoiding "special" non-alphanumeric characters, so we would live in an all-platforms-are-supported world.
Consider substituting an underline (_) or dash (-) in difficult cases. To overcome some length restrictions you can use Abbreviations that are used in other systems that you use. Like your JIRA. Or if you want to push it to extreme - make an Excel sheet in your Dropbox and save abbreviations there.
And to make your system future-proof - leave some space to standardized imperfections. Which you can later standardize.
I do have an example for this formula, but it might be too geeky for now. If there will be a need for it – I’ll post it somewhere. Just don’t forget to find us somehow.
The conventions can be set on many levels of things that you deal with: Server Infrastructure, Code, Git Repositories, Git flows, Domain models. You can pick one of the existing Conventions. You can modify an existing convention to suit your needs. You can make your own one from scratch.
Just, don’t forget about the drawbacks:
- You need to educate people to, actually, use the provided strategy.
- You have to have some supporters
- You all have to comply
We are not robots. Robots don’t care. We DO. We make robots to make care to us. A-la Human. All the randomness is good to prevent auto-crawling and improve security. While naming things in a simple, yet scalable, manner will make your systems more a-la Human. Fellow humans will appreciate it.