DEV Community: Arnaud Spanneut

Document your technical improvements to make them a success 🎯

Arnaud Spanneut — Tue, 15 Dec 2020 00:03:00 +0000

Many software companies are facing the same problem:

How to prioritize Non-functional requirements vs Functional requirements?

Let's explain first which is the difference between these requirements:

Functional requirements: Come from user expectations. Example: Product feature development.
Non-functional requirements: Define the system quality attributes. Example: Architecture evolution.

With the same criticality level, functional projects often looks more urgent than non-functional projects.

The underlying reason come from the fact that non-functional projects are not as well managed as functional ones.

User needs are clear and documented vs. Engineers' needs are in the engineers' minds.
The product roadmap is defined for the next 3 months vs. Non-functional projects are coming when we will have time.

The second point is inherent to the first. Lack of visibility does not give the same priority to a project.

Use the documentation as a tool.

Using documentation to build on have many benefits in large companies.

Having one channel to share and align people.

There are plenty of ways to share ideas in a company. It could be on Slack, JIRA, with a Pull Request or even during a coffee discussion.

Having one channel regroups knowledge and facilitates building.

Include engineers in decision process.

The code base is the day-to-day engineers' tool. It is crucial to let them participate in the evolution of their platforms. It creates ownership and better adoption of the evolutions.

Communicating earlier also prepares engineers for later. It is much easier to participate in a project that is still under consideration than in an RP that took a month to develop.

Educating engineers.

Sharing ideas on a dedicated channel is nice for engineers to learn practices.

Besides, writing is a wonderful exercise to reinforce knowledge. It helps to pose technical problems and solutions in a structured manner.

Build your software history.

Understanding the origin and the timeline of past decisions is priceless in a company. There is nothing better than the written word to preserve the traces of the past.

It's a perfect way to create empathy by understanding why old decisions were made.

AD(R) as a template.

An architectural decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences. [source]

The AD is an excellent model to open a discussion with a structured description that makes it clear to everyone.

It is the starting point for expressing intent and allowing people to share their opinions and build on them.

You can use GitHub's issues or discussions as a tool to run this process. It's nice for writing, organizing, commenting and reacting with emojis.

Any engineer who wants to propose an idea can create a document.

📝 Template

Context / Problems: What is the actual problem of the system? Describe what is going wrong. Why is the current implementation problematic?
Proposition: How do you think it can be improved? Describe how you would like to improve the architecture. Present a plan, add diagrams. The more you're clear, the more you convince that it is a good proposition.
Benefits: Summary of how it will improve the system. Bullet point of good impacts that this proposition will address.
Limitation: How could the project be risky? Each solution has some limitations. List the different difficulties we could face on during the implementation (complexity/maintenance/lack of shared knowledge...).
Deadlines: When do you think it could be done?
References: Add relative links to other ADR, articles, videos, documentation or code.

⚡️ Process

The proposer has to lead this pretty simple process:

Open and complete the template.
Share it and invite commenting and reactions on the proposal.
When a Go is decided: Organize, animate and communicate about project progression.
Deliver it.
Celebrate 🎉.

🦄 Some simple rules

If you want this process to be a success, there is some easy rules to keep in mind:

Do not edit original document, build in comments.
Use voice talking if you're struggling on writing. Then write the note on the document.
Agree to be able to disagree on a proposition.

As any project, be sure that engineers adopt it.

It is engineers' participation that will make it successful by creating a virtuous synergy.

You can nominate facilitators for the process to help people work with it.

Each proposition should be small enough to be done in a short term.

For example, a framework migration which implies a full codebase modification cannot be treated by only one document.

This could be, at least, the beginning of a discussion on how to divide the work and conduct to the opening of other ADRs.

Conclusion

With a better visibility, it is easier to talk about non-functional projects with leads and products.

You can defend them by collecting and sharing engineering feedback. You can also include these projects in the roadmap.

And don't forget to communicate on their success 🎉.

This process can be extended for all decisions that has to be taken in a company. From product features to company organization.

A teammate said once: “ADR is like having a technical discussion at the coffee machine.”

At the exception that is it in a more constructive and inclusive way.

How I saved 4 months of work on a code base migration with Codemod ✨

Arnaud Spanneut — Fri, 20 Nov 2020 15:29:58 +0000

The SimpliField mobile application started in 2014.

At that time, AngularJS and Ionic were at the top 🕺. I decided to start with this stack but JavaScript Modules system was not yet the norm.

Two years ago (2018), I thought it was time to migrate the code base to a new bright system of ES modules. This migration was a good step forward to prepare the next code migrations (TypeScript, new framework...).

The code contained ~600 files with our old friend's IIFE function, an outdated syntax and without any modularization.

I knew that a manual modification creates the risk of introducing bugs.

🗺 The Plan

My plan to was to migrate the codebase incrementally by:

Updating the builder system to run ES module on some folders of the app.
Rewriting folders with export syntax.
importing exported files in a root file.

I estimated at 4 months the time needed to migrate the code base (in parallel with other projects). It seemed like a long and difficult road before being able to start the next improvements.

After 1 months of tedious work, I realized that the road could be longer than expected 😓.

✨ Codemod

And then, Codemod enter the game 🔥.

Codemod is a tool/library to assist you with large-scale codebase refactors that can be partially automated [source]

Codemod is parsing code source into an Abstract Syntax Tree (AST) which is the graph representation of the structure of source code. It provides a simple and comprehensive data structure to work with.

To help you understand code AST, there is a set of useful tools:

AST Explorer: Your best friends for this mission. You can navigate, query and test the code.
EStree: Es tree syntax specification. It provides the documentation of nodes definition.
jscodeshift: Run Codemod over multiple JavaScript or TypeScript files.

🕹 Let's play

I will present a simple example to help you dive in a use case.

But first, go on AST Explorer to configure the editor:

Copy past the old syntax in the upper left
Select @babel/parser in the header (next to JavaScript)
Activate Transform option in the header with jscodeshift
Run and play with the code in the transformer() function in the bottom left.
Enjoy the result in the bottom right

Perfect, you're now ready! 🚀.

This is what we will expect from this example:

// old syntax
(function iife() {
    class HelloWorld {
        say() {
            return 'Hello World';
        }
    }
}())

// result
export class HelloWorld() {
    say() {
        return 'Hello World';
    }
}

We have to apply 2 transformations:

Remove IIFE wrapper
export the HelloWorld class

1. Remove IIFE wrapper

Let's remove the IIFE wrapper to keep only the class. This is what our transformer has to do:

Query the wrapper function
- We will select all the (function iife()) wrapper
- First argument is the tree type we want: j.ExpressionStatement
- Second argument is the node path selector (expression → callee → id → name) with the value iife.
- It can be found thanks AST explorer. Just click on iife value in the upper right and look at the path.
Replace node
- Call Codeshift API with AST node to use helpers.
- Replace the wrapper with his content (the class).


const j = api.jscodeshift;
const root = j(file.source);
// 1. Query AST
root.find(j.ExpressionStatement, {
    expression: { callee: { id: { name: 'iife' } } }
})
    // 2. Loop on AST nodes
    .forEach(ast => {
        // 3. Replace element
        j(ast).replaceWith(ast.node.expression.callee.body.body);
    });

Copy past the code above in the transformer() function in the bottom left and see the result in the bottom right.

2. Add export

💡 Copy past the result of the step 1 in the upper left

Let’s now export the class.

Query the class element
- First argument is the tree type we want: j.ClassDeclaration
- Second argument: for this case, we don't need to query a specific class definition, so we can avoid it.
Loop on AST nodes: .forEach()
Define the new ES tree: j.exportNamedDeclaration(content)
- 💡 Use AST explorer to know the definition of export AST node
- 💡 Use EStree documentation to know the implementation
Replace with the new export definition
- Call Codeshift API with AST node to use helpers2.
- Replace the wrapper with his content → Remove iife


// 1. Query AST
root.find(j.ClassDeclaration)
    // 2. Loop on AST nodes
    .forEach(ast => {
        // 3. Define the new ES tree
        const exportNode = j.exportNamedDeclaration(ast.node)
        // 4. Replace with the new export definition
        j(ast).replaceWith(exportNode);
    });

Copy past the code above in the transformer() function after the code of step 1 and see the result*.*

Et Voilà ! 🎉✨

You now have your exported class without IIFE. And you can run it on all your affected files.

You can now take the first old code and run both transformation and see your new file.

You can access to a full implementation here:

ArnaudSpanneut / codemod-example

Codemod example for the article

👌 Conclusion

With Codemod, you can migrate easily any codebase to new code style with peace of mind.

You need to invest some time on the implementation, but it's totally worth it!

It took me 1 week to implement Codemod and migrate the SimpliField codebase

Implementation ideas

You can do many things with Codemod to transform your code.

Run your updated code style on all the code base.
Split methods from a source file to create one file per method.
Update your code to move to another framework.

Some feedback regarding my experience playing with it:

It is a bit challenging query AST at the beginning.
Create helpers function to help you migrate the code. You can compose your helpers to migrate different files depends on the syntax.
Keeping a style of code in a project helps you migrate files because they respect the same structure.
Use ast.forEach() instead of ast[0]. It avoids adding a sanity check in case of the element doesn't exist in your tree.

Special thanks to Quentin Tardivon and Oleksandr Korneiko for their help on this article.