Stop worrying about the little things

As a developer, I have suffered from the "software engineer syndrome". After taking a quick tour on dev twitter or stack overflow, etc, it's such a relief to see that I am not the only one.

What is the software engineer syndrome? It is a very serious yet really first world problem that developers have about making small decisions. You have probably seen people complaining about stuff like "why do we need semicolons", "use tabs instead of spaces" to name a few but the list goes on (I got you there for a second 😂).

The problem

Something quite common in a few teams I have worked with is that we (developers) spend way too much time arguing about the small things that are not necessarily making us more productive nor are solving any real business problems. Isn't it more productive if we take advantage of tools that solve such problems for us? For example prettier amongst tons of others, it solves the tab vs spaces problem. That way, we don't end up having the same conversation over and over again in Pull Requests reviews.

Another example of such a problem is when creating new files like React components, util functions and other pieces of code that we deal with on a daily basis. Questions may arise like where will this new code live within our project structure? What naming convention shall we use? How will we separate the concerns? Will we include tests?

All these are valid concerns for teams to have, but hopefully after a quick catch up with the rest of the group, a plan can be made. However, that plan needs to be documented so that it is available for everyone to use as a guide. It can also be really valuable when onboarding new developers. That way we keep being consistent and then really hope for the best.

It's not so rare to see that we easily forget (or at least pretend to forget) that initial plan. Then the team changes, new minds with new standards come in and... you know... dev life happened. That results in the code structure taking the wrong direction. Then by looking at the code in our project, it looks like 20 different coding styles were applied and the question "which style shall I follow" soon arises. What comes next is that developers take it personally, start complaining that we need to refactor stuff and arrange a plan to get rid of that infamous technical debt we created. This not only takes a lot of time, but it is possible to bring new bugs to the surface because this massive re-styling is going to touch many many files. So what is the solution here?

Let's aim at the point when we create the code in the first place. How about we let the tools do all the annoying / hard work for us? That will also save us time! You may be thinking "it only takes 2 minutes to create a new folder and add a couple of files in it, why bother?". However, considering how many times we do that per day or week, at the end of the month it may save a lot more time than we think. Ok I think it's time to finally get to the point. 😅

The solution with code-gen-library

To solve this problem, I created a small CLI tool that takes all of these considerations away from our heads. If you want check it out, it is a lightweight npm library called code-gen-library. (Yep the name is not the most creative one 🤣)

How does it work? We simply install it as dev dependency and run it as a script. Yes that simple. Here's a quick preview of how it works.

Once we execute the script, the CLI is going to ask us to input some details. The first one is the name we want to give to the new component. If the name is more than a word, the scripts will convert it to pascal case. For example if we type "input text" then the file will be called InputText.

Similarly we can separate the concerns so that models, styles and tests (coming soon) are also generated in separate files using the same naming convention followed by a suffix for the specific concern. For example the TypeScript model for "input text" will be InputText.models.ts.

The new component will then be exported via the index file. Why via the index file and not directly? I don't know about you but I find it quite frustrating when we have import paths that look like ../components/InputText/InputText. By exporting via the index file, we avoid that duplication. A few devs in order to prevent that duplication from happening, they add the component code into the index file. Then when we have multiple component files open, our text editor will result showing multiple tabs for index.js files which is not so easy to read. By limiting anything that has to do with importing files from that folder to have to go via the index file, we use the best of both worlds. At least I hope so 😅

Customising our config

Now the next question you may have is about the ability to customise. Like every other CLI tool out there, we have a cgl.config.js file. The config file will be used to customise what the CLI asks us to input. If we don't include that file, the code will fall back to the default settings.

The ability to customise was one of the main drivers for creating this library. Another one was to ensure consistency and stop these pointless arguments that re-appearing all the time. Once the team decides the style to follow then they can setup this library accordingly and no need to worry about it again.

There are a lot of things in the todo list for further customisation, including specifying custom new files and more. This library currently includes the preferable setup that is used in my personal projects.

The inspiration

One thing I remember from my PHP days (don't make fun of me please 😆) is that frameworks had some really useful CLI tools. My favorite one was a command called scaffolding which was basically generating a whole MVC codebase along with a database migration file. All I had to do is follow a templated command and pass a few arguments on how the MVC files are going to be called and also some schema for the DB migration. I LOVED that! It really saved a lot of time as it would generate a whole page within a few seconds. Apart from that every single model, view, controller, etc looked EXACTLY the same from a code structure point of view.

Then when I moved to the JavaScript world. More specifically to React which back then was the wild West of the programming world. The first thing I complained about was "do we have to write everything, every time from scratch?". Given that JavaScript is a language that does not have any strong opinions on what kind of structure works the best, we end up having these kind of conversations all the time.

Summary

I personally use that kind of tools A LOT and hopefully others may also benefit from that as well. Because this is the JavaScript world, I really expect that there will be many arguments on the specific structure chosen within this library. There are some ideas on how to make that better. Let me know what are your thoughts about code-gen-library.

Stay consistent.