Read this before you start a project
Let's assume you want to create something - a tool, a micro-service, a program, a side-project of sorts.
Let's also assume that you (or your team) have done the hard part of conceptualizing what it will do. What it is supposed to achieve. The restless coder in you wants to fire up that IDE and start hacking.
More often than not, a product starts with something small. A basic requirement that needs to be fulfilled. A basic ask. A tool that takes in X and gives out Y. The mentality here is to create something quickly that does the job and be done with it. Have you ever said - "I hacked it over the weekend."
This approach seems to work fine initially. Specially, when the tool is used internally by 3-4 users. But in the lifecycle of any good tool or service, there comes a time when:
- It needs to be used by someone other than your team-mates.
- You want others to contribute to the codebase.
- It needs to interact with a third-party (or internal) tool or service.
This is where things start to get messy. A completely sane piece of code could turn into an unmanageable monolith.
Imagine staring at a repository with 80+ scripts, having weird names pleading to be refactored.
So, how do you make sure that your side-project is future-proof? What do you do now (before even writing a single line) that will allow for collaboration and scale without compromising on time to deployment. How do you build a product over a weekend rather than hacking it up.
Don't Hack, Build.
This is not a guide on good coding practices. This is just a set of directions or guiding principles we use at Cliff.ai whenever we embark on any little micro-service or project.
Input -> black_box -> Output
Break it down.
Always, call whatever you are building a Black box. Draw a box on a paper or excalidraw.com. ✏️ Next, clearly write down what is the input and output for that box. What do you expect the user to provide and expect from the Black box. It could be a set of parameters or a link to the database or a queue. Once this is done, move on to breaking down the contents of the black box and so on.
Search whats already there
No point re-inventing the wheel. ☸️
When you distill your idea to the bare bones, you can start searching for solutions that are already out there. You will either find a solution or a part of it. If you don't, what better motivation than this to create one for yourself! 😀
Work with templates
Don't code for yourself, code for your team.
Code as if today is the last day you'll be working on the project. Not because you hate it...but because you'll be handing it to the next person to take over.
The next person should be able to understand and add new features in a systematic way.
Our friends at Verloop use a modified version of cookie-cutter repos . We use a super-template that has all basic functionalities like testing, CI/CD via githooks and deployment methods like fastapi, dockerfiles and k8 manifests baked in.
This could vary with teams but creating a template makes sure the boilerplate code is handled before you even start coding and it also ensures the whole team is on the same page.
Release small changes regularly
Don't just ship once. Keep on shipping. 🚢
Chose a deployment method while planning the project. Even if you decide to change it later, your template (as mentioned above ☝️) will allow you to change that fairly quickly. Whatever deployment you chose, keep deploying at regular intervals.
- It helps in keeping control on the bugs per release. A huge release is always harder to manage.
- Ensuring you have quick wins. That helps to keep spirits high. 🎉 Spread good cheer.
Having worked in teams who have hacked tools and built tools, I chose building them every time. The reward for spending extra time preparation and planning just keeps on giving.
- Less stress when a new feature is requested.
- More confidence in the scalability of the tool or service.
- Easy collaboration
A good team should improve themselves incrementally with every project. It usually starts with learning from their own mistakes and evolves into implementing good industry practices. This journey and the positive changes have always intrigued me. In this series of blogs I will explore and try to understand those minor changes that make a big difference. As a team, We've set out on a journey to increase our collective knowledge and we'll try to document our findings so it might be of use to other teams as well.
Try implementing this the next time you or your team starts something new. Also, get back if you have something cool, a method or trick that will help us. I am available on firstname.lastname@example.org .