Creating your own "Code Language"

Firstly, sorry for the clickbaity title. In this article, a "Code language" (CL) refers to a project's code style. Similar to how a Design System determines the visual identity of a project/company; a CL determines the syntax and project structure from an architectural perspective.

This article isn't a "step by step" guide on how to create the best CL. I want to give everyone some of my thoughts and hopefully spark a discussion on the subject with the wider community.

This concept isn't anything new. Searching for "Creating a coding standard" will return tons of articles all giving their pros and cons around the subject. However, I think that if done right, a CL can help with readability, productivity, onboarding and allow team members to share their opinions to create a better code base.

The Why

I recently started working on a new product that I want to launch and possibly monetise, because of this, I knew that I couldn't do what I usually do; which is, writing dirty (sometimes hacky) code and finishing with a product that is unstable and can only be saved with a complete refactor. I needed to set some ground rules for myself and others that would help with the project (if I ever get to that stage).

My Approach

Rather than set very strict do's and don'ts, I decided to set some rules that would help with readability. These rules don't stand in the way of productivity and some can be caught with linting rules or CI tools.
Below are some examples of my "rules":

1. map, filter, reduce etc requires named functions, not inline functions.
This will help keep code condensed and separates functionality for easier testing and allows you to easily expand the complexity of the function if needed.

✅ [].map(funcName)
❌ [].map(() => {...})

2. async/await instead of Promises.
When making a call for data, use async/await instead of resolving Promises.

✅ const fetch = async () => { const data = await ajax(url) }
❌ const fetch = () => { ajax(url).then(...).catch(...) }

So far, these rules are not standing in the way of productivity, are only helping with readability and allow for condensed code that can easily be expanded when business requirements change. If any of these rules can't be followed, the developer can simply add @see <url>, in the comment documentation, to allow other developers to see why the rules were ignored.

These rules are not just limited to code; for my project, I created rules that also apply to Git commits, branching and Folder Structures, etc.

Folder Structure

A good folder structure helps developers to easily find and create different components (React for this project). Below is an example of the folder structure I am planning on using:

ComponentName
  - ComponentName.tsx
  - index.ts
  - helpers
    - function.ts
  - __test__
    - ComponentName.test.ts
    - function.test.ts
  - __spec__
    - ComponentName.stories.tsx

This structure allows all of a 'component's functionality', 'functional and visual tests' to be isolated, making debugging easier.

This structure does seem cumbersome to create manually however, using tools like ccr or creating your own internal CLI will allow this structure to be automatically generated.

Shameless plug. An example CLI that I created for a different project.

Git Workflow

These rules apply to how team members create commits, branches and the review process. The workflow I came up with is pretty simple and has probably been done a million times. Below is an outline to how I handled branching:

1. High Level Branches - master, test/*, dev
2. Task Level Branches - Create a new branch for each feature, bug, story etc and add a ticket ID or a small description for the task
   1. feature/24
   2. bug/no-confirmation-email
   3. story/login-flow
3. Delete your local and remote branch when merged with a "higher" level branch.

Tools

There are plenty of tools available that will allow you to create rules, and code that will stay consistent when handled by multiple developers. Below are some that I use frequently:

1. Husky - Husky can help prevent bad code from being committed.
2. eslint - Allows you to create style guidelines for your code.
3. Prettier - Helps to keep all code formatted the same way.
4. BundlePhobia - Checks a package bundle size before adding it to a project.

Closing thoughts

You will need to create your CL rules with your team but it shouldn't spark a week-long debate; attempt to solve as many of the issues with automated tooling and catch anything else in the code review process. When a new rule is introduced, enforce it from that point onwards and only refactor code when there is time. The main idea behind a CL is to help with productivity, give newcomers a set of rules to follow and to help with code readability; not to create a cycle of refactoring and tension between teams.

I think that creating a Code Language can have a similar effect to a Design System; it helps to remove guesswork since many decisions have been made for you and you can finally focus on creating the product.

What are your thoughts?

Thank you for reading my article, it really means a lot! ❤️ Please provide any feedback or comments, I'm always looking to improve and having meaningful discussions. This article was written as part of my #myweekinjs challenge, I have other interesting articles there if you are interested in learning more.

👋 until next time!