The Push

We rebuilt our platform from scratch: here's what we learnt

Mattia Sinisi — Wed, 11 Mar 2026 08:22:53 GMT

Preamble: A bit of context on where I am in my career

Since my last article a lot has changed, both for me and for the world of software development in general. The biggest leap was, of course, the meteoric rise of AI systems, especially in the software development space with new tools such as coding agents.

Like these AI systems, I have also grown and learnt a lot in these past years, I have changed companies 2 times, I went from a software consultancy company called Key2 Business, to my first product-oriented company called Everli (a grocery delivery application). Here I was the youngest, less experienced developer in my team, and I was followed carefully, everyone took their time in teaching me best practices and design patterns for effective collaboration on our codebases (which were unlike anything I had seen up until that point), thanks to them I went from an okay developer delivering code quickly to a more careful and pragmatic thinker when it came to implementing new feature or solving old bugs.

The best resource I gained was a new way of thinking and approaching problems in a more meticulous fashion.

Then, after a couple of years, I decided to leave the company. A decision I made with a heavy heart, since the synergy of the group was something I feared I would never encounter again, I felt really lucky to be a part of that team.

That fear was short-lived though. I got hired as as Senior Full-Stack Developer at a company called Contents, an AI-driven content creation and orchestration platform. The team I met was small yet highly productive, they were navigating a complex shift in vision that would decide the future of the company: “are we B2C or B2B focused?” was the prevailing question at the time, a particularly difficult question to ask, since these 2 markets have drastically different approaches.

For B2C you have the freedom to read feedback, do research, test features and THEN maybe ship them.
For B2B the client dictates everything, most importantly how much time the team had to complete the work.

So there it was: a codebase torn between 2 worlds struggling to accomodate either one of them, a team with very little time to implement anything cleanly and a rising technical debt.

“Make it work” was the mantra

Here’s the story of what once was, the processes we adopted to change everything from the ground up, the amazing results we accomplished, and what key lessons I learnt along the way.

The old platform(s): A post-mortem

In this section we discuss (without breaking my NDA) the state in which I found the platform when I joined and what caused it to be so.

We all love a good roast, especially when it comes to bad codebases. “Look at the mess they’ve made! Let’s point and laugh!” is the tone adopted by most articles discussing such matters, but alas it’s useless, it only brings ridicule to what COULD have been a learning experience. Let’s try, then, to write a small post-mortem, explaining the many (and I mean many) fallacies of the codebase and try to extract valuable advice for future implementations.

Lack of consistency

When trying to run against your competition, especially in the AI market in 2021-2023, quick development decisions and pivots are almost a weekly occurrence, in this environment the priority is speed, with consistency and code quality as an afterthought.

So it goes, every developer on the team implemented everything in the quickest and dirtiest way possible, and everyone had their own way of writing code, resulting in a codebase without standards, without design patterns, where every piece of code did a number of things obfuscated by incomprehensible variable and method names, where entire chunks of code were duplicated and re-implemented except for a couple of lines, where logic was partly implemented on the backend and partly on the frontend, and where if statements stretched into the hundreds of lines, each added after every reported bug.

We had a complex and incomprehensible maze of dependencies, where changing how a date is displayed to the user broke the login and who knows what else.

Lack of agency

At the beginning of each sprint, which lasted about a week, a new set of tasks without descriptions was assigned to the tech team, each new feature was implemented by the marketing and sales team without consulting with the rest of the company, resulting in meetings to discuss what to do (which ate a lot of the already limited development time), without discussing how. That thing needed to be done, and it needed to be done in a week, “figure it out, devs” was the only directive most of the time.

When we started writing code no consideration was given to how long something took to implement, or better ways of implementing it, the client had already signed a contract, and we needed to uphold it no matter what. And so another week of rushed development began. No agency to the developers whatsoever, this would be one of the first things that needed to change.

Lack of documentation

Each second of development time was very valuable, so no time was given to creating a proper documentation where one could outline standard, best practices, code style guidelines, architectural decisions, and code philosophies to uphold during the development process. Everyone did things their own way, on top of the maze of mismatching design patterns that was already there. But no time to think, no time to document, there’s only time to implement.

Lack of reviews

Since no time could be dedicated at the start of development to write documentation, no time could be dedicated at the end of development for code reviews. And how could we? The two are interlinked. No standards were set in stone and written down so, even IF we had time to do code reviews, the reviewers would not have any standards on which to base their judgement upon.

Lack of communication

No communication whatsoever between the teams, no communication whatsoever between members of the same team, no communication whatsoever with the clients… you know how this ends. When one of the tech teams needed to implement, for example, an endpoint so that other tech teams could perform actions on their service, they would just do it with no consideration of how the others could implement it and then move on to different things, wasting time and massively increasing the code complexity of whoever needed to interact with that service.

The lack of documentation and reviews was also deeply ingrained with this issue as well.

There was never a time where all teams were on the same page on the status of the platform, or even on what the parts of the platforms did what. Everyone was lost in the same fog as everyone else.

Interlude

Let’s take a brief moment, nestled between the old and the new, to give praise to the people that stuck in there. It’s easy to assume that nobody gave a damn, but that’s not true.

Everybody recognized these issues, everybody wanted and tried to solve them (in multiple occasions!), each in their own way, the only thing we lacked was a unified company-wide voice.

Now, after the changes you’re about to read, the mood is electrifying, everyone is firing on all cylinders and are happy to do so. We’re building a lot (and I mean A LOT) of cool new stuff.

So thank you colleagues, thank you for not giving up and for the amazing work culture that we managed to build.

Without further ado… it’s time to break some stuff!

The shift: How to structure a complex project’s workload

Each new feature was taking longer and longer to implement, slowing us down considerably with each new deployment, in the course of a couple of weeks we drafted a rough roadmap of what we wanted to do and presented it to the entire company, the pitch was simple yet crazy.

“Let’s throw everything out, let’s recreate the platform from scratch” — we said, unified.

We were given an opportunity that few tech teams had, we were given the green light to stop what we were doing and re-build the entire platform from scratch: new features, new UI, new code, new everything… the only thing that remained unchanged was the name.

Finding our direction

At the beginning of this odyssey we discussed how the platform was torn between two worlds: B2B and B2C. We had to make a decision of which one to prioritize, we went with the B2C in the first phase of the refactor. The company decided the features, and the tech team would give time estimates.

No longer were be beholden to the whims of the market, we were going to build our platform, from our ideas, with our philosophies.

Plan, then act

The first major change we applied was to the project management itself, we didn’t implement re-actively anymore, we now implemented pro-actively.

Each feature was proposed by the product designers in a rough document and it was then discussed with the tech team (where it was often reshaped, enriched and improved), after that the tech team would brainstorm possible implementations and come up with a technical document from which we wrote the tasks and give estimates back to the product design and project management team.

Every problem and feature would be broken down into multiple, self contained releases. Each release was easy to estimate and implement, no longer we had big tasks that would take entire weeks, we now had simple and well defined tasks and goals that could be brought to completion in (at most) a couple of days.

Key takeaways

Trust your developers, their job isn’t to simply write code, but to find solutions, don’t treat them as the very last step of the implementation process
Include your developers straight from the ideation phase, not just when it’s time to build
Spend more time arguing back and forth at the beginning, ensuring smooth sailing once everything is decided
Document every decision, a lot of time can pass between planning and implementing, you want to make sure that everything is on the same page even a month from now

Documentation is not a “time-waster”

Every discussion and every subsequent decision could not vanish into thin air, or be relegated to the memory currently working on a given project. Every time a choice was made we dedicated some time to extract more generic rules and guidelines that could be applied to similar decisions in the future.

We decided to adopt a “case-law“ approach to decision making, similar to how lawyers build cases based on previous, similar ones.

Doing this made every meeting a bit shorter than the one before, whilst unifying the tech team (and, as a result, the codebase itself) into a more cohesive and comprehensive whole.

Key takeaways

Spending a lot of time at the beginning of a project writing documentation is a worth-while investment that facilitates both the current and future developments
Time spent to plan and to write documentation is not extra, is just as important as writing the code itself

Strict standards

There’s no way to sugar-coat this one: once something is documented, you need to be strict about enforcing it. While the field of software development can involve a lot of artistry and creativity, you don’t want every developer to implement stuff in their own special way.

Spend time at the beginning of a project to define (not on your own, but with the rest of the team) software design principles and patterns, naming conventions, protocols, code-style guidelines, and everything in between, then enforce those standards with a strict review process before shipping the code to production.

The process

Write your code and add or update feature/unit tests for it
Open a pull request (may have different names depending on your VCS)
Describe your changes inside the pull request
Let the automatic test-runners and lint-checkers go over your code
Add at least 2 fellow developers as reviewers
Make sure your branch is aligned with the destination branch
If needed, implement changes requested by the reviewers
Merge your code with the squash strategy (to collapse all commits into one)
Release in a safe environment for one last round of testing
Release in production

Key takeaways

A feature that works, but with unreadable code, is worse than no feature at all
Take your time in the review process, even on multiple rounds, there’s no rush to go live
If there is a rush to go live, mark your “quick and dirty” code and assign yourself a task to go back and beautify it later
If you find bad code (that works) make it compliant with the defined standards, following the “boy-scout rule“

The new platform: Software design principles and best-practices

After more than a year of refactoring, rebuilding, redoing, re-everything-ing, we are now happy with our current codebase. Let’s now go over the key design decisions that made our code a joy to work with!

Keep in mind: these principles do not apply to a specific language or framework, however they ARE tailor-made for backend API-based web applications.

Domain-Driven Design

Every feature of our application is treated as if were an external plugin developed by entirely unknown people and each relegated to its Domain.

In the first phases of the refactor we separated domains into folders inside the same codebase to allow quick development:

src/
    Core/
    Domains/
        Auth/
        Projects/
        Products/
        Payments/
# etc...

Then, after each of those domains was solidified, we packaged and versioned them into a private registry so that the main application simply needs to install that package.

package-manager install our-company/domain-name

Each domain needs to be built with the assumption that all others, except for the Core domain, do not even exist. Each domain must stand on it’s own.

Maybe we don’t even need Auth tomorrow because we’ll build a local-only version of our platform, maybe not, we don’t know and we don’t care.

Apply the “single responsibility principle“.

Domains and components of the domain each do one specific thing, regardless of context.

Dependency injection between domains

Each domain must have at least one so-called Provider, a piece of code that declares and (indeed) provides dependencies to be used by other domains. Each domain must use dependency-injection to use another domain’s components, it must never EVER instantiate components directly.

// src/Domains/Payments
class PaymentsProvider extends Core.Provider
{
    public function register(): void
    {
        this.add();
    }
}

// src/Domains/Plans
class PlanManager
{
    public function checkActivePlan(payments: PaymentsInterface): void
    {
        // other stuff...
        payments.unresolvedPayments();
        // other stuff...
    }
}

We want components to be swappable at any time without changing a single line in the rest of the codebase.

Everything must be predictable

Functions:
- Must declare strongly typed arguments and return types
- Must declare all the exceptions that COULD be thrown
- If execution completes the result is considered valid, if not throw an exception. Don’t make the caller check for the validity of the result once returned, its not their responsibility
Variables:
- Must be strongly-typed or at the very least type-hinted. The developer and whatever tools they’re using must be able to inspect what a variable is

Layers and responsibilities

Each domain is (usually) composed of 3 main layers, each with their own job.

Database

Were data is persisted and where consistency checks are made. The database layer does not care if things make sense from a business standpoint.

Let’s say, for example, that we decide that each user can have, at most, one project associated with them: in this case we build our database to make sure that the relation between users and projects exists but we do not enforce the described limit, we want this layer to be as open as possible, knowing that any limitations can be lifted in the future.

The less we update this layer, the better.

Logic

Here we only care about implementing the entities and actions, without checking if a particular user can or cannot perform it… actually, we don’t even concern ourselves with the concept of “user” here, just the raw logic wrapped inside atomic components that can be called from anywhere at any time in any context.

Each component of this layer requires the utmost care and rigorous unit testing.

When an action is called (be it a function or method) it either returns successfully or throws domain-specific and self-explanatory exceptions.

Interaction and Presentation

In the context of an HTTP-based API application, this is where we define our endpoints, validate requests and their payloads, check if the authenticated user can perform the desired action, and build responses.

This is just a wrapper for the Logic layer, where, once all the necessary checks are performed, we call upon it to perform the action and interpret its result (or its exception). More on that later

Components

Each component is a piece of code designed to perform a specific type of action. Here are the main ones we defined:

Entity: a representation of a non-primitive piece of data, can be used by other domains
Repository: to store and retrieve data unconditionally and without complex logic, never called outside a service and cannot be used by other domains
- storing: an entity is given as an argument, it persists it to the database and returns the updated entity
- fetching (one): returns the requested entity from the database or throws an exception if it cannot be found
- fetching (list): returns a list with the requested entities from the database or an empty list if none can be found
Service: to interact with a repository based (occasionally) on complex logic, can be used by other domains
Controller: to manage a specific API endpoint, perform user-based checks call services, and format responses, it NEVER contains complex logic, can only be used by external clients

Naming conventions

Casing
- camelCase (lower) for variable and function names (i.e. project = projectService.getProject())
- camelCase (upper) for class names (i.e. ProjectService)
- snake_case (lower) for raw data, like payload keys and values (i.e. {"some_key": "some_value"})
Always use the same word for the same action: if the piece of code that persists data to the database is called storeSomething in one place, then it must also be called storeAnotherThing elsewhere, the action is store, and is always store
Self explanatory: while documenting your code is certainly recommended and encouraged making your variable, class and function names explain what they do makes everything more readable. Here are our designed function/variable prefixes:
- can/is: return a boolean true if yes, always use positive language, never use cant/isnt
- check/validate: return void if all checks pass, throws exception if not
- just the action name: performs the action, can return any type of data, throws exception if it fails.

Protocols (for HTTP requests and responses via JSON )

The request and response payload share the same guidelines.

snake_case for the payload (as described in the naming conventions for raw data)
Train-Case for headers (as defined in the HTTP standard)
an existing null key and an absent key are the same
keep it raw: let the clients do the interpreting and parsing (i.e. for dates we send the UNIX Epoch timestamp instead of a date string)
same entity, same structure

Wrapping up

After doing all that (and way, waaay more) we now have a consistent and predictable codebase. Productivity has increased (making the managers happy) and the code is beautifully maintainable (making the developers happy)… It’s now time to take it to the next level!

AI-Assisted Development (done right)

Since they made their splash on the software market, my feelings on AI coding assistants were always mixed: on one hand the theoretical productivity boost is too good to ignore, on the other having a model generate code could and has lead to inconsistencies in many documented cases.

Finding the right model

After snooping around and experimenting with various models it became clear that the best coding agent, at the time of writing is Claude Code... but what do I mean by "perfect"?

Here's the criteria used to evaluate the quality of a coding companion:

The underlying model must be un-opinionated (or as close as possible to it); no model is truly un-opinionated, but we found that ChatGPT and Copilot tended to follow in the same footsteps of similar projects that used the same framework as us, instead of following OUR standards
The agent's actions must be configurable
The agent must first generate a plan and then, only after authorization from the human user, it may start writing the actual code

Managing contribution scopes

Every model has the same issue as of right now: as the context grows, the results lose consistency and quality.

This is why it's important to limit the work done per-request. Keep in mind that our codebase was already well-formed before we introduced our AI companions to help out, so we only employed them to implement additional features on an already robust and well-segmented codebase.

Every time a feature needs to be implemented we define a clear and limited scope, complete the generation and then log our decisions in our technical design documents. These documents are then read by the agent on the next iteration so it knows where to start from, keeping the context light and the quality high.

The most important rule is that the code being generated MUST be written the same way we would so, if at some point in the future we ditch our AI companions, we can still understand and navigate the code it generated.

Creating the "perfect" companion

Before making our AI companion start writing code, we defined a small fleet of sub-agents, each with its own goal and guidelines. For each code generation we make them collaborate and check each other's results to ensure that the code is written the way one of our developers would.

Some useful sub-agents we implemented are:

documentation compliance checker: runs at the end of each generation to ensure that everything is done according to our documentation
domain expert: writes the scaffolding for new domains and informs the code writers on how to work on an existing one (folder structure, service + repository design pattern, providers, etc.)
coding standards enforcer: makes sure the code being written matches the coding standards, naming conventions and design patterns we declared
testing expert: writes and/or updates unit and feature tests for the features being implemented and makes sure the existing tests still pass
api validator: make sure that the endpoints being implemented follow RESTful and our own standards
etc.

With these agents (and more) each generation goes as follows:

A plan is drafted by interrogating domain and coding standards agents, included in the plan is also a list of which agent needs to be called and when
The plan is approved by a human user
A fleet of agents is run in parallel to implement the feature
Compliance, coding standard and test checks are ran by the relevant agents
The feature is sent for a final round of manual review by a human user
Done!

The productivity boost this approach has granted our team is hard to overstate, it's NOT just vibe coding, its a strong workflow that allows us to treat our agents as a small team of qualified developers, who always follow OUR way of doing things, with hallucinations reduced to a minimum.

Conclusion: Looking back, looking forward

I feel like I took part in something rare, a company that is willing to put everything on hold for a year, even in troubled times, because it understands and trusts its developers to take their time and deliver a quality product is really hard to come by.

When I first joined I was frustrated at how things were managed both in code and in person, I wanted out… but something beckoned me to stay. I’m now sure that something was the group of people along side me, willing to doubt themselves and tread on unknown grounds, willing to build something great, simply… willing.

I, like everyone else in this world and especially in this line of work, don’t know what the future holds, but I’m ready to face it, to predict it, to build it, and to learn from it.

Thank you for sharing a bit of your time with me, I hope to ave made it worth your while.

The Giant List of useful resources

Mattia Sinisi — Sat, 26 Mar 2022 13:14:32 GMT

For the past 2 years I, and many others, have been using a lot of small tools, apps, and alike to support us during our development process.

I've taken some time to compile them and list them for you here.

I love talking with and meeting new people at conferences and workshops, a lot of what is listed below was discovered by talking with other passionate developers.

The List

Tools, apps, articles, tutorials, cheatsheets, components, assets, and more to aid developers and other online professionals in their work. Some of these are also useful to spice up your presentation and others are just cool. I'll let you discover them.

Special mentions

This next tool was suggested to me by its creator after the publication of this article, in fact, this paragraph has been added afterward.

The opinions I'm about to express are my own and no one else's.

The tool in question is Bulk Page Speed Test and, by its name alone, you already understood why it's so useful. The loading and crawling speed is amazing, you could test your whole site in under a minute (depending on its size, of course), truly an amazing tool!

The End

Wow! You made it! Y-you didn't just skip through right?

Anyhow, if you enjoy this type of stuff I can post a new edition with new stuff I discover or that is linked below in the comments. *wink wink*

Thanks for reading! 😁

How to automatically map JSON data to a TypeScript object

Mattia Sinisi — Wed, 20 Oct 2021 10:20:00 GMT

Introduction

Interacting with JSON APIs, files, configs, etc. doesn't have to be such a hassle. Keeping your code clean and maintainable can be difficult when using loosely-typed data that can change at any time and, as I've talked about in my previous article about Anti-Pattens, it introduces a lot of hard-coded logic in more than one place.

The situation 🤔

Let's say that we need to map some JSON data to our TypeScript class. The incoming data looks like this:

{
    "_param_1": "something",
    "param2": "something else",
    "items": ["item 1", "item 2", "item 3"],
    "something": {
        "inner1": "inner thing",
        "inner2": "another inner thing"
    },
    "thingToBeIgnored": "some useless data"
}

While our class looks like this:

class TestClass {
    public param1: string;
    public param2: string;
    public list: string[];
    public thing: AnotherClass;
    public thingToBeIgnored: string = "Leave me here!"
}

How do we go about mapping one to another?

The bad way 😑

Of course, the most cumbersome (and most used) way of doing it looks something like this:

function mapToClass(json: any) : TestClass {
    const result = new TestClass();
     result.param1 = json["_param_1"];
    result.param2 = json.param2;
    // ...ok I think you get the picture.
}

Doing it in other ways will NOT ensure a true instance of our class.

The ONE-LINE alternative ✨

For this we will need tapi.js , a tiny, zero-dependency, auto-mapper for TypeScript.

npm i -S tapi.js

Next, be sure to enable decorators in your tsconfig.json file.

"compilerOptions" : {
    "experimentalDecorators": true
}

Now, let's decorate 🌹 our class and make it buildable. In our case it looks something like the following, however you can read the docs to better understand the process.

import { BuildableResource, Properties } from "tapi.js";

@Properties.Resource
class TestClass extends BuildableResource {
    @Properties.Alias("_param_1")
    public param1: string;

    @Properties.Transform(incomingValue => {
        return incomingValue.toUpperCase();
    })
    public param2: string;

    @Properties.ListOf(string)
    public list: string[];

    public thing: AnotherClass;

    @Properties.Ignore
    public thingToBeIgnored: string = "Leave me here!"
}

Let's convert! 😍

Now your conversion happens automatically... in both ways and respecting the original formatting of the JSON data!

From JSON to class

let instance = new TestClass().fromJSON(data);

From class to JSON

let data = instance.toJSON();

Mapping from promises 🤞

Wanna use it with promises? Simple!

import axios from 'axios' // 👈 Of course, you can use whatever library you want

import { BuildableResource, ... } from 'tapi.js'

import 'tapi.js/extensions' // 👈 Use this line to import all the extended functionalities of core types

// Let's create a simple class...
class TestClass extends BuildableResource {
    // You know the drill by now...
}

// Then make a request and get a promise...
axios.get('/some-url-that-returns-an-object')
    // Now let's build the object with its defined builder! 🎉
    .as(TestClass)
    // Aaaaand we can use the typed object to do whatever we want.
    .then((builtObject) => {
        builtObject.doSomething();
    })

Conclusion

I hope this article and this tool is helpful to you in some way, I'm actually the author of the NPM package and would love four you to try it and give me some feedback.

I've used it in a lot of projects and can assure you that it works... but don't take MY word for it, take YOURS!

Until next time! 👋

Anti-Patterns

Mattia Sinisi — Tue, 21 Sep 2021 12:57:19 GMT

For about a year I've been working in a bigger company than the startups I was used to. Suffice it to say, there's a lot of new lessons I've learned that I want to share with you. Working with experienced developers taught me how much a supposedly "clean" solution can fully reveal itself as a pain in the ass during the final steps of a project.

These are what developers and engineers refer to as "Anti-Patterns".

A wolf in sheep's clothing

I'm using this overly dramatic title to illustrate a key concept: an anti-pattern may seem like a good idea, an optimization, not unlike its benevolent counterpart the design-pattern... however it's actually ruining your future progress and will make you lose a lot of time in case your project needs a new feature.

The following article will explain the most common anti-patterns and how to avoid them.

Some of these are mistakes I've made and trust me... they're not pretty, especially when close to the deadline.

Optimizing too early

What is it?

This could quite possibly be the most important out of all the other ones, that's why I put it before all the other ones. Keep in mind that, in this case, the word optimizing is used for both execution speed and code cleanliness optimization.

Most developers like to build a solid structure (that covers most, if not all, use cases) before tackling the actual problem, almost like a mini-framework just for the project.

This, when done correctly, often leads to a cleaner codebase and faster development times... however, it's not a foolproof strategy.

Why is it bad?

The thing about solid structures, though, is that they're really hard to move.

Optimizing early in the process can lead you to be restricted by your own code.

What I mean is that it can lead you to have a confusing codebase with little to no room for improvement. In the best of cases, you would have to re-write big chunks of code just to make a smaller adjustment just before you didn't consider it while building that initial structure.

The solution

The best way to go about optimizing your code is to finish writing a working implementation first, and optimizing it after all the edge cases have been tested and addressed.

Just like a tattoo, you need to be really sure of it.

Magic numbers

What is it?

This refers to the seemingly innocent practice of putting string literals or number directly in your code. Of course, this is the most common and most forgivable anti-pattern, it's almost inevitable if you think about it.

Why is it bad?

However, remember what I said before, anti-patterns look innocent, but aren't. Putting data and code together means what you'll have to rebuild and redeploy your entire application every time you want to tweak one of these values.

See? The general rule of thumb should be never hard code anything... ever.

The solution

Make at least 99.9% of your variables configurable externally, most applications use .ini, .json, .yml or even a simple text files to store these values. Any solution could work, even using an external database (although I wouldn't recommend this one).

Re-implementation Hell

What is it?

It's the bad practice of writing the same thing (or something very similar) more than once. Plain and simple.

Why is it bad?

Let's say that you write a simple function used only in one part of the code, maybe even as a private method of a class, now days go by and you (or, worse, someone else) need to do the same thing you did, should he re-write it? Of course not, but you left no other choice.

This leads to bloated code and makes it harder to fix any bug that your function may have, since it now needs to be solved more than one time for every copy of your function.

The solution

Instead of writing code for very specific situations try to write it as if it were to be included in a library, in that scenario it should work for a wide range of use cases by users you'll never meet. Using this mindset allows you to write more adaptable code, reducing repetition across your codebase.

However... there is a fine line between generic and too generic. Let's see why!

Single point of failure / Too much responsibility

Yes, I'm contradicting myself... well, kind of.

What is it?

While having a class, component or service that does a lot of things can seem practical it can lead to some unexpected results.

Why is it bad?

If a lot of your codebase is dependent on a single piece (or only a few pieces) of code then, in the case of a failure, the majority of your application (if not the whole thing) will be brought to a screeching halt.

It's the same thing with servers:

You wouldn't want ALL of your company's services running on the same machine. I hope not!

The solution

Every component of your application needs to have one job and one job only. It's better to use a lot of smaller components than one big, heavy and beefy one. Dependency Injection and microservices help a lot with this.

Conclusion

If you find some of these common errors in your codebase then a good ol' refactoring is in order! Learn how to effectively re-structure your code with this in-depth article by Tiger Abrodi entitled "The importance of refactoring".

Here you can also find The big list of the most common anti-patterns. Enjoy!

Thanks for your attention, have a nice rest of your day!

What a good framework SHOULD do

Mattia Sinisi — Mon, 05 Oct 2020 19:49:31 GMT

I'm sure that many of us developers, to make our work easier, had to use - or in some cases build - a variety of frameworks that aim to simplify our workflow.

A framework, by definition, is a bit of support logic that helps the developer; following this interpretation one could assume that it is a tool to organize your code, however, as Rich Harris (the creator of Svelte ) puts it:

A framework is a tool to organize your mind.

Following this concept, developing using such a tool should let us focus more on the concepts unique to our app, rather than everything that comes between a blank project and a working demo (i.e. configuration, helpers, and base logic).

So, why did I use the word "should"? Simple, it's because not every framework does that. Which brings me to this article, here I'd like to list what, in my opinion, a good framework should let me do in order to build the app I wanted.

Remove repetitive actions

Whatever your project is, whatever language you use, there are some things that you ALWAYS have to do in order to get it up and running, even as a crude prototype. If these actions are always the same, why then must I repeat them every time?

As an example, let's say that you have an application that needs to retrieve pieces of information from a database. The connection and subsequent disconnection shouldn't be something that I have to worry about every time, so how about a framework that lets me do this?

Database.from('posts').get(['title', 'content', 'author']);

Be customizable / Not get in the way

Simplicity is all fine and dandy, but what happens when a developer needs to perform an action that the developer of the framework didn't consider?

Especially with open-source tools, I should be able to access the framework's API at a lower level of abstraction in order to carry out my task.

Better yet, I should be able to declare new features specific to my application and append them to whatever the framework is already exposing.

Let's get back to my example, imagine if after the information is retrieved the developer still wants the connection to be open, but our make-believe framework does not have such an option, how can we work around the problem?

We could try to modify our helper, effectively messing with the original code, or the framework could expose something to let us customize the behavior. Let's see what that could look like:

Database.from('posts').get(['title', 'content', 'author']).after(function(connection) {
    connection.keepOpen();
});

Using a framework should give you an advantage, not slow you down or make some actions impossible.

Be understandable

As a framework becomes more and more advanced it will expose more and more methods and parts of its API, this often translates into unending piles of function names and configuration parameters.

At this point, more than ever, the developer could begin to feel overwhelmed by all this functionality if it's not presented in the right way.

At this point, the way you write in and of itself must be clear, self-documenting even! Let me share with you a perfect example of this from the beautifully cohesive Laravel:

// Here we are getting all the users living in Italy
// and returning them alongside their siblings
User::where("location", "Italy")->with("siblings");

This could work for something as simple as this following example taken from a random unit test written with the help of Jest:

// Here we are... well, you can guess it
expect(2 + 2).toBe(4);
expect(1 + 1).not.toBe(10);

To conclude this article I'd like to once again thank each and every one of the members of this community for responding so positively and critically to my previous 2 articles, it really helped me a lot with my writings.

Let me know what you think on this subject!

Writing code for others

Mattia Sinisi — Wed, 23 Sep 2020 13:51:33 GMT

Today I'd like to talk about collaboration in developer teams of all sizes.

Introduction

When everyone begins coding it's most likely that they'll learn and experiment all by themselves, that's perfectly fine, It's how I and almost anyone I know first began. As you begin writing (by yourself) any sort of application your top priority is to make it work, which means having your codebase organized in such a way that makes sense to you.

It's really easy to follow the flow and write for long periods of time without anything stopping you, and that way you'll have your application up and running in no-time.

Knowing that I'd like to ask you this: have you ever revisited an old project of yours?

If so your first reaction would be something along the lines of: "Wait, did I write that?"

That's completely normal, when you're the only person who's going to see that code it makes perfect sense not to worry about legibility or even having a loose structure - often called design pattern - to follow.

It's only when you add other people to your team that you begin to discover that a lot of what you've written is almost incomprehensible for someone new to your project.

Improving your code facilitates collaboration

0. Define a design pattern

A good way to start a project, especially an open-source one, is to clearly define the rules of your codebase: where everything goes and how the jobs are distributed.

To do this I've compiled some useful techniques that will greatly improve productivity and legibility.

1. Separate logic

Everything in your app should have a specific job that it does well, all other components should treat those containers of logic as a black box, only accessible through functions / methods that you've defined.

You should be able to modify (or even change a component) without touching the rest of your application. A good way of doing this (if your environment supports it) is via dependency injection.

If you're not comfortable with it then you should divide everything into sections, or better yet, create small libraries to handle that type of job.

Nothing should EVER be written twice.

2. Naming conventions

Naming things is one of the hardest things in programming.

Let's imagine that you've successfully followed the first section and now your code is organized into different sections, now let's imagine that your team does not have access to them but can only use your functions / classes / helpers by calling them, at that point they should know what everything does just by looking at what's available to them: the name.

This subject is nothing new, even George Orwell has written about good writing and naming rules, but a good rule of thumb is to avoid looking at your code for about a week and then trying to understand what everything does just by the name.

A good way of keeping names consistent is by defining naming rules early on. As an example, can you guess what this line of code does?

ItemManager::orderByName()

3. Take some time to write documentation

Naming conventions have their limits, you should avoid writing super long names; so, to help your team you should take some time at the end of your project to write a small documentation or wiki.

Better yet, if you're lazy like me, you should comment every usable thing in your codebase and then use auto-documenting tools to convert them to a small wiki.

Conclusion

I hope that this article was helpful to you or to your team, having a clear codebase is something that makes or breaks your organization. You shouldn't waste more time finding the issue than resolving it.

Thank you for reading!

How open source saved our business

Mattia Sinisi — Mon, 21 Sep 2020 13:58:07 GMT

Introduction

I'd like to start by giving a little background information about my work experience. Like many developers trying to make a name for themselves, I too started as a freelancer; my work consisted of simple client applications or RESTful APIs.

While working on all sorts of projects the CEO of a tiny startup called me and asked if I was interested in working long-term with them: this was like a dream come true.

You see, the atmosphere in a startup is very different from that of a traditional company, there's a lot more experiments with new technologies, much more freedom to try new things.

There's also another aspect that defines a startup, one that is largely ignored while discussing them: the shortage of money.

Initial struggles and our breakthrough

Building a large-scale application without funding can be difficult - schedules need to be respected and tons of hours are spent working on a project without the certainty of it ever being finished or used - and to optimize work as much as possible we heavily relied on open source frameworks and libraries.

This is not what saved our business though, using it just meant that we worked less on problems that had already been solved. The major breakthrough was publishing some of our work as libraries. Our thought process was this: "If this app fails then we'll have wasted our work, so let's publish it and hope that someone else would find it useful".

That was the best decision we had ever made.

Our libraries were quickly noticed by other fellow developers and word got out about who we were and what we stood for. Working for free and giving to the public were major selling points for us.

Eventually our name reached some investors who saw our projects and began giving funding, a new startup had solidified. After months of uncertainty, standing on stable ground was a great sensation, we did it without marketing, without sponsors, we succeeded just because we had created something useful.

Takeaways

Ever since I've witnessed the power of a good open source project, and the effect it could have on a company I vowed to always distributes my most frequent work as packages or libraries.

Even when working with bigger companies I always suggest publishing libraries to get our name across, build an image of developer-friendliness that can boost our brand and - most importantly - have a bigger audience to test parts of our code as independent and useful products.

I hope you join me as well. Thank you for reading.

The Push

We rebuilt our platform from scratch: here's what we learnt

Preamble: A bit of context on where I am in my career

The old platform(s): A post-mortem

Lack of consistency

Lack of agency

Lack of documentation

Lack of reviews

Lack of communication

Interlude

The shift: How to structure a complex project’s workload

Finding our direction

Plan, then act

Key takeaways

Documentation is not a “time-waster”

Key takeaways

Strict standards

The process

Key takeaways

The new platform: Software design principles and best-practices

Domain-Driven Design

Dependency injection between domains

Everything must be predictable

Layers and responsibilities

Database

Logic

Interaction and Presentation

Components

Naming conventions

Protocols (for HTTP requests and responses via JSON )

Wrapping up

AI-Assisted Development (done right)

Finding the right model

Managing contribution scopes

Creating the "perfect" companion

Conclusion: Looking back, looking forward

Further reading

The Giant List of useful resources

The List

Special mentions

The End

How to automatically map JSON data to a TypeScript object

Introduction

The situation 🤔

The bad way 😑

The ONE-LINE alternative ✨

Let's convert! 😍

From JSON to class

From class to JSON

Mapping from promises 🤞

Conclusion

Anti-Patterns

A wolf in sheep's clothing

Optimizing too early

What is it?

Why is it bad?

The solution

Magic numbers

What is it?

Why is it bad?

The solution

Re-implementation Hell

What is it?

Why is it bad?

The solution

Single point of failure / Too much responsibility

What is it?

Why is it bad?

The solution

Conclusion

What a good framework SHOULD do

Remove repetitive actions

Be customizable / Not get in the way

Be understandable

Writing code for others

Introduction

Improving your code facilitates collaboration

0. Define a design pattern

1. Separate logic

2. Naming conventions