Rotating them every 90 days means generating new keys, updating environments, and hoping nothing breaks in the process.

And really, why keep replacing long-term credentials every 90 days? That’s just turning long-term creds into short-term ones the hard way. Why not start with short-term credentials from the beginning and avoid the problem altogether?

How does OIDC work?

That's where the OpenID Connect (OIDC) protocol comes in. Through a series of verifications between GitHub and AWS, it provides short-term credentials instantly to run the GitHub workflow and use resources from AWS.

This protocol has three main actors

• Github workflow

• GitHub as an Identity provider

• AWS STS as Authorizer and credentials issuer

Let’s have a general picture of how the communication flows between these actors:

1. GitHub, acting as an identity provider, issues a token when the GitHub workflow begins.

2. A GitHub Action aws-actions/configure-aws-credentials sends this OIDC token to AWS STS via the API call AssumeRoleWithWebIdentity , along with the IAM Role Arn and optional configurations like the TTL.

3. STS validates the token against the OIDC identity provider you configured in AWS IAM, comparing its properties against the trust policy configured on the IAM Role, and returns short-term credentials in case of success.

4. The workflow now uses those short-term credentials to run AWS CLI commands, Terraform, CDK, etc, using the same permissions as the IAM role has defined

Here is a Sequence-System Diagram of the above flow:

What is AWS STS?

AWS STS (Security Token Service) is an AWS service that allows you to request temporary security credentials for AWS resources instead of using long-term IAM user access keys.

These temporary credentials are:

• Short-lived (from a few minutes up to a maximum of 12 hours, depending on the request).

• Scoped to specific permissions (defined by IAM roles and policies).

• Automatically expire, reducing the risk if they get exposed.

It’s the key player on the OIDC implementation with AWS.

Key uses of AWS STS:

1. AssumeRole – Allows one AWS service, user, or external identity (like GitHub via OIDC) to temporarily act as another role with specific permissions.

2. Federation – Provides temporary credentials for external users authenticated by identity providers (like Google, Active Directory, GitHub).

3. Cross-account access – Lets you securely access resources in another AWS account without creating permanent users.

4. IAM role session management – Useful for apps, CI/CD pipelines, or temporary jobs that only need short-lived access.

Contrary to what you might think, this OIDC process falls under the second use case: Federation. This is because, initially, you don't have any AWS credentials. AWS federates an external identity into AWS to generate short-lived credentials. In other scenarios, you begin with AWS credentials and request temporary credentials to assume a role or start a new session for security reasons.

How does the AWS STS validation process works?

Here is a flowchart that describes in detail the validation process AWS STS performs to issue short-term credentials. This provides a deeper look into points 2 and 3 from the previous picture showing the general communication flow.

In simple terms, the validation process goes like this:

• AWS checks whether it has configured GitHub as an identity provider.

• It then verifies the authenticity of the OIDC token by checking if it was issued by GitHub and confirming its TLS certificate or thumbprint.

• It verifies the token signature.

• It compares the token payload claims against the properties set in the IAM Role trust policy, such as repository, branch, environment, sub, etc.

• If everything is correct, AWS STS issues temporary credentials that are returned to the caller.

Conclusion

OpenID Connect (OIDC) lets your GitHub Actions talk to AWS in a secure, short-lived, and trust-based way. No need to deal with long-term access keys ever again.

With OIDC, you can ditch static credentials, skip the rotation headaches, and set up fine-grained permissions that map directly to your repo and branches. It’s cleaner, safer, and follows AWS’s best practices for least privilege and temporary credentials.

So really, what are you waiting for to switch to OIDC?

Next steps

In the next article, I’ll walk you through how to set up OIDC between AWS and GitHub step by step, so you can securely assume roles without adding extra complexity.

That was my situation working for a client with a multi-repo project using numerous testing tools. We had Jest, Jasmine with Karma, and the trio: Mocha, Sinon, and Chai; for unit and integration tests in different repositories, plus other supporting tools like rewire and proxyquire, and mock utilities.

The Problem

Some problems with this setup are quite clear:

• Switching between libraries, even for the same task, because you need to work with code in different repos.

• Many unnecessary package updates due to new features and outdated packages.

• No unified way to write tests.

• Constantly needing to check different documentation pages whenever you write a test.

It was something:

❌ Difficult to work with

❌ Tedious

❌ Exhausting

For us, using a single testing library seemed a better option.

The Decision

As a team, we decided to standardize the testing tools across the repositories by migrating all tests to a single tool and removing the others.

We chose Jest because it is modern, stable, and has excellent documentation. We appreciated that it includes everything we need, like expectations and mock utilities, and offers many customization options if required. Additionally, our current team has extensive experience with Jest.

Another advantage is that it’s widely used by developers, making it easier to find someone who can start writing tests right away if needed.

🚧 Disclaimer

For simplicity, in this article, I used Jasmine as the old testing tool we wanted to migrate from in favor of Jest. However, the same principles and strategies discussed here can be, and in our case were, applied to mocha and other testing tools as well.

The Plan

If we were going to do this, we needed to make a few agreements.

Since we had hundreds of test files per repository, and migrating those files wasn't automatic or our main priority, we had to ensure they were migrated to Jest incrementally.

✅ Allow incremental migration

As the migration would happen slowly and incrementally, we had to ensure the project was never left unprotected. Regardless of the migration stage, the old and new testing tools should coexist and work together until the entire migration is completed.

✅ Never leave the project unprotected

Another consideration was maintaining a coverage threshold as a check in the CI pipeline. Therefore, during migration, we needed to keep a single coverage report to set the CI check, regardless of the migration progress.

✅ Keep a single coverage report

After considering the above rules, the resulting plan was divided into four main stages:

1. Set up → Install Jest and assign each tool a portion of the tests: new tests will run with Jest and old tests with Jasmine. Also, add a script to run both testing tools together with a single command.

2. Merging → Combine testing results from Jest and the old testing library into one coverage report.

3. Migrating → Gradually move old tests to Jest and remove them from the old test runner.

4. Cleaning → Once all tests have been migrated, delete the old configurations and uninstall the old testing library and dependencies.

This article will focus on the first two steps, as they allow us to safely begin migrating incrementally without leaving the project unprotected.

Setting up the two testing libraries to work together as one

The idea is straightforward: we want to move from Jasmine to Jest. From now on, new tests should be written to work with Jest, while existing tests will continue to be handled by Jasmine until they have been successfully migrated to Jest.

First, install Jest and create a jest.config.js file at the root directory.

// jest.config.js

module.exports = {
  collectCoverage: true,
  coverageDirectory: '.coverage',
  coverageReporters: ['json', 'text', 'text-summary'],
  collectCoverageFrom: ['<rootDir>/src/**/*.js'],
  testPathIgnorePatterns: ['/node_modules/'],
  roots: ['<rootDir>/src/']
};

To let these testing libraries know which tests they should handle, it's important to define a way to distinguish new tests from old ones and apply this distinction in the testing libraries' config files.

There are several ways to do this, so it's important to choose the right strategy to direct the test execution to be handled by both libraries.

Subfolders strategy + tests folder

One strategy, if your project already has a tests folder outside the source code, is to create a subfolder for each testing library and move the test files there. Initially, all tests will be in the Jasmine folder. As you start writing new tests and converting old ones from Jasmine to Jest, the Jest folder will gradually fill up, and the Jasmine folder will eventually become empty.

project/
├── src/
│   └── auth/
│       ├── login.js
│       ├── signup.js
│       └── token.js
└── tests/
    ├── jasmine/
    │   └── auth/
    │       ├── login.spec.js              # Jasmine test
    │       └── token.spec.js              # Jasmine test
    └── jest/
        └── auth/
            ├── signup.spec.js             # ✅ Jest test
            └── passwordReset.spec.js      # ✅ Jest test

Following the file structure above, the config files should look like this:

// jest.config.js

module.exports = {
  collectCoverage: true,
  coverageDirectory: 'coverage',
  coverageReporters: ['json', 'text', 'text-summary'],
  collectCoverageFrom: ['<rootDir>/src/**/*.js'],
  testPathIgnorePatterns: ['/node_modules/'],
  testMatch: ['tests/jest/**/*.spec.js'],
  roots: ['<rootDir>/src/']
};

// jasminerc.json
{
  "random": false,
  "spec_dir": "test",
  "spec_files": [
    "tests/jasmine/**/*.spec.js"
  ],
  "helpers": [
    "helpers/**/*.js",
  ]
}

We configure each library to find and run tests only within its respective subfolders.

Suffix strategy

Another strategy, if you keep test and production code in the same folder, is to leave the test files in their original location and add a suffix to the old test files to show which testing library was used to run them. This will help us indicate to the old testing library how to find them.

For new tests, the extra suffix is not needed because we will configure Jest to only look for tests without the .jasmine suffix. These will be identified as new tests to be run by Jest.

project/
└── src/
    └── auth/
        ├── login.js
        ├── signup.js
        ├── token.js
        ├── login.jasmine.spec.js           # Jasmine test
        ├── token.jasmine.spec.js           # Jasmine test
        ├── signup.spec.js                  # ✅ Jest test
        └── passwordReset.spec.js           # ✅ Jest test

To instruct Jest to run all tests except those with the .jasmine suffix, we need to add that expression to the testPathIgnorePatterns property.

// jest.config.js

module.exports = {
  collectCoverage: true,
  coverageDirectory: 'coverage',
  coverageReporters: ['json', 'text', 'text-summary'],
  collectCoverageFrom: ['<rootDir>/src/**/*.js'],
  testPathIgnorePatterns: ['/node_modules/',  '/src/**/.*\\\\.jasmine\\\\.spec\\\\.js'],
  roots: ['<rootDir>/src/']
};

For Jasmine, we need to set it up to run only the tests with the .jasmine suffix and skip the ones without it.

// jasminerc.json
{
  "random": false,
  "spec_dir": "test",
  "spec_files": [
    "src/**/*.jasmine.spec.js",
    "!src/**/*[!jasmine].spec.js"
  ],
  "helpers": [
    "helpers/**/*.js",
  ]
}

Suffix strategy + tests folder

The suffix strategy can also be used if your code organization mirrors the same file structure inside an external tests folder.

project/
├── src/
│   ├── auth/
│   │   ├── login.js
│   │   ├── signup.js
│   │   └── token.js
│   └── payments/
│       ├── charge.js
│       └── refund.js
└── tests/
    ├── auth/
    │   ├── login.jasmine.spec.js        # Jasmine test
    │   ├── token.jasmine.spec.js        # Jasmine test
    │   └── signup.spec.js               # ✅ Jest test
    └── payments/
        ├── refund.jasmine.spec.js       # Jasmine test
        └── charge.spec.js               # ✅ Jest test

In this case, you don't need to create separate subfolders for each tool inside the tests folder, nor do you need to move the test files. The only requirement is to add the .jasmine suffix to each test file meant to run with Jasmine, no matter which folder they are in. All tests without that suffix should be run with Jest.

The resulting configuration in both files is the same as when using the suffix strategy, except that in this case, the tests should be looked at inside the tests folder rather than the src folder.

How to choose the correct strategy to separate the test execution

It all depends on how suitable the strategy is for your tests files organization

• Use folders when:

  • You want a clean, enforced separation between legacy and new tests.

  • Your tests are already in a root-level tests folder.

  • Your team prefers a directory-based organization, and you can afford some initial overhead.

  • You don’t mind moving files from one folder to another.

• Use suffix when:

  • You want minimal disruption to the existing organization.

  • Your tests are tightly coupled with the source code in the same folders.

  • You need an easier and faster path with fewer moves, relying on naming conventions instead of reorganization.

Write the npm test script to execute both test runners sequentially

Once Jest is set up to run the new test files and Jasmine is set to run the old test files, you just need to trigger both test runners with a single npm test command.

I also suggest adding two extra scripts to run each test runner separately. This will be helpful when you start migrating tests.

Your package.json scripts should look like this:

"scripts" {
    "jest": "npx jest",
    "jasmine": "npx jasmine",
    "test": "npm run jest && npm run jasmine"
}

Now, when we run the tests, both testing libraries will execute one after the other. To prevent failures, it's important to configure them to pass even without tests. At the start, there will be no Jest tests, and after the migration, there won't be any tests written for Jasmine. Therefore, it's crucial to run the tests with a flag like --passWithNoTests.

Merging coverage results into a single report

Since we use the coverage report as a pipeline check, we need to keep using it even after making the two testing libraries work together. We must merge their coverage reports into a final report that includes all tests, regardless of whether they were written for the old or new testing tool.

In our project, we decided to use nyc to combine the coverage reports from Jest and Jasmine. We were already using it to collect coverage for Jasmine tests, and it offers two useful commands for merging reports: merge and report.

Since we noticed some inconsistencies with the merged report using the merge command, we opted to use the report command instead. We decided not to stress over the minor differences when comparing the coverage results to the original results from using just one testing tool.

To correctly use the report command of nyc, ensure reports don't overwrite each other by storing them in different folders when possible and renaming files if they need to be in the same folder.

To merge the coverage reports, the plan goes like this:

1. Run Jest and collect the coverage of Jest test files into a temporary .coverage-jest folder.

2. Run Jasmine and collect the coverage of Jasmine test files into a temporary .coverage-jasmine folder.

3. Copy both coverage reports into a single temporary folder .coverage-merge, and rename the files by adding a suffix to identify the testing tool that generated them, preventing overwriting.

4. Run the nyc report command, specifying the final thresholds and the temporary folder where the reports are located. Also, indicate the output folder where the merged coverage will be saved.

5. Clean up all temporary files and folders.

💡 It's important to set the coverage threshold as flags when calling nyc report and remove any threshold from the Jasmine and Jest configuration files. This is necessary because we need to validate the threshold across all files, not just a subset.

If you follow the steps described here, you'll end up with a package.json similar to the one below—I hope one much better —. We use the shx package to run commands across different operating systems to delete, copy, and move files and folders.

"scripts": {
    "copy-coverage-jasmine": "npx shx mv .coverage-jasmine/reports/coverage-final.json .coverage-merge/coverage-jasmine.json",
    "copy-coverage-jest": "npx shx mv .coverage-jest/coverage-final.json .coverage-merge/coverage-jest.json",
    "copy-coverage-files": "npx shx mkdir .coverage-merge && npm run copy-coverage-jasmine && npm run copy-coverage-jest",
    "clean-tmp-coverage": "npx shx rm -rf .coverage-jasmine && npx shx rm -rf .coverage-jest && npx shx rm -rf .coverage-merge",
    "multi-coverage": "npm run nyc-jasmine && npm run jest && npm run copy-coverage-files && nyc report --check-coverage --lines=80--branches=70 --functions=70 --statements=80 --reporter=lcov --reporter=text --reporter=text-summary --temp-directory=.coverage-merge --report-dir=./.coverage && npm run clean-tmp-coverage"
 }

With the scripts above, instead of running npm run test:coverage, you would use npm run multi-coverage. It's up to you if you want to make it explicit that the coverage is from multiple tools. And that's how you make two testing libraries work together, keep the coverage functional, and set the stage to gradually start migrating tests from one tool to another.

✍🏻A couple of notes to keep in mind

• The final coverage script runs sequentially. It depends on which testing tool you run first in your npm test script. So, if the first tool fails, the next one won't run.

• Merging reports isn't perfect. There are open issues about it, so pick the command that gets the resulting coverage closest to your current value and adjust the thresholds accordingly.

Up next:

• We’ll learn to use tools to make the migration less tedious

• Advice on what to pay attention to and how to migrate the tests without leaving the project unprotected

• How to get rid of all of this config to leave a single testing tool after the migration

Tools We'll Be Using

Cursor (🔗 https://www.cursor.com)

Cursor is a developer-focused IDE with AI built right in. You can switch between different models and agents, all powered by your OpenAI API key (unless you’re paying Cursor directly to use theirs).

Some standout features:

• Understands your codebase and adds context to prompts

• Runs commands for you (with your approval)

• Spot bugs and offers fixes

• Autocompletes like a champ

• Built-in smart reviews

It’s VS Code on steroids, with some real AI muscle.

Ngrok (🔗 https://ngrok.com)

Ngrok is an API Gateway service that handles everything related to your API so that you focus on your business rules without worrying about secure connections and infrastructure. While it offers a full suite of infrastructure tools, we’ll focus on Webhook testing, which gives us a public URL to test a local server.

Ollama (🔗 https://ollama.com)

Ollama is a fantastic open-source tool that lets you run LLMs locally. You can pull supported models, serve them through a local API, and even customize or train your own.

Browse available models at ollama.com/library

Let’s Get Started

1. Pull LLMs with Ollama

Once everything’s installed, the first step is to pick and download an LLM. Just a heads-up: LLMs are resource-hungry. Bigger models need more RAM and CPU, so make sure your machine can handle it.

To install a model:

ollama pull <model>

For example:

ollama pull gemma3:4b

You can check installed models with:

2. Set Up Ngrok

Create an Ngrok account and enable Multi-Factor Auth (highly recommended). Then, install the CLI and connect it with your account by running:

ngrok config add-authtoken <your-token>

The command above will set up your computer to connect securely with the Ngrok Web platform, but it won’t secure any endpoint you later expose.

🚧 Heads up: Your Ngrok endpoint exposes your local server to the internet. Even on the free plan, Ngrok gives you options like auth, IP filtering, and rate limits. Worth setting up later!

3. Run the Ollama Server with Ngrok

Ollama can serve your model through a local API. Start it like this:

OLLAMA_ORIGINS=* ollama serve

By default, it runs on port 11434.

Now expose that port with Ngrok:

ngrok http 11434 --host-header="localhost:11434"

Ngrok will generate a public HTTPS URL, called “endpoint” in the ngrok language, that maps to your local server.

We now have a public URL to connect us from the internet to our local Ollama server, It’s time to tell Cursor how to use this URL to hit our Ollama server locally.

4. Connect Ollama to Cursor IDE

Add Your Model

In Cursor, go to Settings > Cursor Settings > Models.

You’ll see some defaults, but they likely won’t match your locally installed model names. Hit + Add Model and enter the exact model name from ollama list.

Override OpenAI API Base URL

Scroll to the OpenAI API Key section and expand Override OpenAI Base URL.

Paste your Ngrok HTTPS URL here. You can put anything in the API key field, it’s not validated in this case since our API doesn’t have any authentication method enabled yet.

5. Test the Setup

To make sure everything works, you should:

• ✅ Be running the Ollama server

• ✅ Have Ngrok expose port 11434

• ✅ Have your LLM registered in Cursor

• ✅ Set the Ngrok URL in the API override

Now, toggle the Enable OpenAI API Key slider in Cursor’s settings. It’ll ping your API to confirm the connection.

If there's an error, Cursor will pop up the response — super useful for debugging.

Once it connects, you’re good to go! Start chatting with your local LLM in the left panel.

Make sure to:

• Switch prompt mode to Ask or Manual

• Disable automatic model selection

• Manually pick one of your local models

Takeaways

Congrats — you’ve got a local LLM running and integrated into your dev workflow.

That said, performance varies depending on your hardware. Try a smaller model (1b or 3b parameters) if your machine struggles. Models like 7b and up usually need at least 16GB of RAM.

And don’t be afraid to experiment. Pull multiple models and see which works best for your use case.

Also, remember: you don’t need Cursor or Ngrok specifically. All you need is:

• Ollama to run the model locally

• Some way to expose it via a fixed URL (Ngrok, localtunnel, etc.)

• An IDE that lets you set a custom OpenAI API base URL

Next Steps

• 🔄 Automate it all
  Right now, everything is manual. Consider scripting the startup, spinning up the server, and tunneling with one command.

• 🔐 Secure your endpoint
  Even if your CLI is authenticated, your public API is wide open. Use Ngrok’s free auth and rate limits to avoid abuse. But then set the API Key in Cursor to successfully connect it to the API.

• 🔗 Claim a static Ngrok URL
  Ngrok lets you claim a static domain for free. This means you won't have to update Cursor every time you restart the tunnel. Just be sure to lock it down properly if you go that route.

How did I get my first job

I was a third-year college student about to start my vacations, the only moment when I could do one of the two internships required to apply for my degree.

At one moment, I saw a job application that caught my interest. I called and had a remote meeting with the founders of a startup company looking for people to assemble their first team.

They were a B2B company selling a solution to reduce the costs and time spent in the last mile problem (The journey between when a package leaves the warehouse and arrives at your door). They were looking for developers to build a web platform for administrators and a mobile app to be used by the delivery guys.

Photo by freestocks on Unsplash

The meeting went right, and they asked me to have a technical interview next week. I got nervous because I had zero experience in technical interviews and also coding real projects, but I had an idea, I was going to spend the whole week working to show them what I was capable of doing.

I was inexperienced in crafting software, but I spent that week learning the technologies they were using to design and code the mobile app they were looking for.

After that week, I presented them with a totally functional proof of concept of the mobile app...they were speechless. As you might guess, I got the internship, and later I got hired, but more impressive it was that they kept talking about that moment to every new hire for the next five years I worked there.

I didn't know back then, but what I did was called the briefcase technique.

💼 The Briefcase technique

According to Ramith Sethi from I'll teach you how to be rich, who name the technique, the secret to selling yourself and the main idea behind the briefcase technique is to SHOW, DON’T TELL.

The technique consists of two parts:

1. Gather information about the client
   • What are they selling?
   • What are they looking for?
   • What are they working on?
   • What tools are they using?
2. Look into the future
   • Brainstorm how you can add value
     • Building a Proof of concept?
     • A design change?
     • Your experience leading teams?
     • Creating a plan to improve skills within the team?
   • Show your proposal highlighting the value you'll add working with them

As you notice, with this technique, the work starts even before you meet the client or future employer. You research their business and try to spot specific issues, pain points, challenges; things you could solve or do better for them. This will position you better compared with a person who is just answering questions like in any interview.

Think about interviews as auditions instead of boring questionnaires and make them easy to say to you YES by shifting the discussion about you to what you're capable of doing by using an effective proposal to solve their problems.

🗂️ The portfolio era

In my story, I recognize that having that first meeting was crucial to pulling off the briefcase technique, but I got that meeting just because I was a college student, and back then, that was enough to catch companies' attention. Now, I wouldn't stand a chance even to get noticed without more evidence of my skills and experience.

These days being a college student or having a degree doesn't have the same relevance as it was before because people realized that provable skills are more important than theoretical knowledge.

You need to show what you've built. This is the Portfolio era!

What projects should you leave out of your portfolio?

Not everything you build is worth showing off.

A portfolio is your presentation card to the world to tell what you can do that makes you stand out from the competition. Therefore, any kind of project that's repetitive and common should be discarded immediately.

Projects like:

• ❌ Calculator
• ❌ Todo list
• ❌ Pomodoro app
• ❌Your portfolio website 🙄
• ⚠️ Clone apps

Projects developed for learning purposes are good for serving as examples in your blog posts and for documenting your process, but not for your portfolio. Why? because everyone had coded one of those at some point, and remember, you want to make an unforgettable impression.

Cloned apps are a special case because if they're functional enough, they could serve to show off your UI/UX knowledge or your skills in building complex systems. So, It's ok to include them, but don't make them the main point of focus; treat them as complementary projects.

The Outstanding Portfolio

For any job, there will be skills that you won't have because you don't have the technical or domain knowledge the company needs, and that's ok.

It's impossible to know EVERYTHING.

You should put your time and energy into building the skills that transcend particularities and are required for any software development role.

Like:

• 👥 Team Player
• 🧠 Problem-solving
• 📐 System design
• ✅ Code quality (tests, clean code)
• 💡 Creativeness/Innovation
• 📚 Active learning
• 🚀 Deployment

The key is to demonstrate those skills through multiple projects. To help you with that, I've classified the projects - that your outstanding portfolio needs - into three main categories that groups the skills earlier mentioned:

1. Projects to show everything you've learned so far

Here is where you put: Experiments, theory, crazy algorithms, libraries. The idea is to show what you've been learning so far.

(Pathfinding Visualizer App)

In this video, Clément Mihailescu tells us that he built an algorithm visualizer for his portfolio, which helped him to get a job at Google.

2. Projects to solve a real problem, starting from one of your own

Here goes probably the most interesting projects you can show because that's what we do, that's our job, to solve problems!

It was used by real users? Then talks about it! What problems did you have? How did you solve them?

Those are the things we want to hear!

The solution will catch people's attention no matter how simple it's.

That's the case of Katherine Peterson. She built readme.so, a website to quickly create a README.md file.

The website caught Githubt's attention, and she got interviewed thanks to the project. In the end, she accepted an offer, and now she is working there.

3. Projects to collaborate and build in public

Working with more people on the same project is a good indicator that you'll work fine within a team because you've real experience in coordinating work among a team, listening to ideas, and solving human problems.

Also, building Open Source projects and publicly talking about your progress makes people get interested; remember that you've to think of getting a job as an audition.

The most important thing about your portfolio are the projects and content, not the website itself

Alyssa Xhas built a ton of good projects but look at her portfolio's website; it's dead simple.

It can probably be enhanced with pictures of her projects but what it's interesting is when you enter each link and see the repositories, articles, and things she has built.

The portfolio has everything. Well, some things are not working now, but it had blog posts, templates, ideas, real products, and so on.

It doesn't have to display only apps

Photo by Amélie Mourichon on Unsplash

It's a mistake to think that a portfolio it's just a website exhibiting other websites. That works for a UI developer, but what if you're a backend developer?

Portfolios are an entry point to display what you've done. Not restricted to only whole functional apps, you can show designs, diagrams, research papers, ideas, talks, benchmarks, and even the thought process you follow when facing a challenge.

One last piece of advice

Recently I've been reading a book on neuroscience applied to sales, and it's surprising how our brain works.

Did you know that 85% of buys are made from an unconscious decision?

We're emotional creatures, and I know that doing all that I said is hard and takes time, but if you need the job soon and you don't have your amazing portfolio yet, it's ok to try your luck by just asking for the job (but you've to give a good speech).

I can guarantee it works sometimes.

We still have things to grasp. One of them was motivated after listening to a chapter about refactoring on the SyntaxFM podcast, Highly recommended podcast, at some point Scott said something that confuses me for a moment.

"...another benefit you could gain from refactoring here is performance enhancement..."

I get what Scott is saying but performance is more related to optimization and that's why we'll discuss in this article what are the differences and similarities between optimization and refactoring and why often when we refer to "optimizing code" we are actually talking about refactoring.

What confuses people: Both alter code

Refactoring

Refactoring is the discipline used to alter the code without changing the observable behavior. The goal is to refine the code having as criterion simplicity, readability, and maintainability.

👨‍💻 Impact on users

After refactoring, the software keeps working as usual, and the changes remain unnoticeable to the users.

Since the changes happen at a structural level (code), only the team involved is aware of the changes.

👩‍🏫 Example

Before

if (orientation === ORIENTATION.PORTRAIT ||
    orientation === ORIENTATION.PORTRAIT_UP ||
    orientation === ORIENTATION.PORTRAIT_DOWN) {
    // Put your logic here
}

The above example may not seem challenging to read, but imagine having that piece of code spread all over your code. Whenever you see an if that starts with the same comparison, you'll lose time verifying it's the same if statement; otherwise, how to be sure it is doing the same?

To avoid that mental overhead and take advantage of reusability, we can put that comparison inside a function and use its name to reveal the intention.

function isPortrait(orientation) {
    return (
    orientation === ORIENTATION.PORTRAIT ||
    orientation === ORIENTATION.PORTRAIT_UP ||
    orientation === ORIENTATION.PORTRAIT_DOWN
    );
}

Now instead of having the same if statement repeatedly. We'll replace it with a call to the new function. Since the function is self-explanatory, it's easy to get what it does.

After

if (isPortrait(orientation)) {
    // Put your logic here
}

Unfortunately, not all refactors are as easy to do; many involve breaking dependencies, writing or rewriting classes, protecting our code from third-party libraries, implementing abstractions, and even deleting unnecessary code.

Optimization

Optimization has a different purpose. Its goal is to improve software's performance. Generally involves satisfying a specific metric to accomplish a nonfunctional requirement . The metric could be to reduce memory, CPU usage, or response time; it depends on the problem you're trying to solve.

👨‍💻 Impact on users

Same as with refactoring: Change the code, not what it does

Users may detect something has changed even when the functionalities remain the same. This effect happens when the difference after the optimization compared with before is too evident.

The most noticeable changes are when the application responds faster, can handle more concurrent operations or doesn't hang when a heavy file is loaded.

👩‍🏫 Example

In JavaScript when people want to reverse a string usually we write a function like the following:

// Reverse string using built-in array's function
function reverseString(str) {
    return str.split('').reverse().join('');
}

Since in JS strings don't have a reverse method but arrays do, we rely on the built-in functions split and join to convert the string into an array and use its reverse method to finally join the reversed array into a string again.

The above code solves the problem but there are more performant solutions like converting the string into an array and swapping the elements at both sides:

// Reverse string via swapping elements in-place
function reverseString(str) {
   const chars = str.split('');
   const length = chars.length;
   let temp;

   for(let i=0; i <= Math.floor(length/2); i++) {
       temp = chars[length - i - 1];
       chars[length -i  - 1] = chars[i];
       chars[i] = temp;
   }

  return chars.join('');
}

Just for you to know, the solution that offers the most consistent fast results in multiple browsers is the classic for loop with concatenation.

If we were offering this functionality as a parsing utility, users wouldn't notice any change in the results unless they work with huge strings. In that case, they would witness the app takes less time to finish or not hang anymore when working with larger strings.

Why it's important to know the differences?

(source: Working Effectively with legacy code, page 7)

During our careers, we'll spend the majority of time working to preserve behavior, either by refactoring or optimizing code.

Therefore, it's important to understand their differences and tradeoffs to make better decisions.

In the reverseString example, the most used solution was the first, even when the second performed better. Why is that?

💡 Hint : What do you think we invest more time as devs? Reading code or writing code?

We spend more time reading!. Therefore, unless optimizing resources becomes a crucial task to the project, we'll always prefer an unoptimized and straightforward solution instead.

Take the increasing use of map, filter, and reduce array methods in JavaScript as reference. Apparently, for loops are no longer accepted even when demonstrated to be more efficient; that's because these array methods are much simple to understand compared with an imperative solution.

const prospects = devs
      .filter(dev=> /python/gi.test(dev.experience))
      .map(dev => ({ 
                   phone: dev.phone,
                   firstName: dev.firstName,
                   lastName: dev.lastName,
                   email: dev.email,
                   socialMedia: dev.socialMedia
      }));

OR

const prospects = [];
for (int i = 0; i < devs.length; i++ ) {
    if(/python/gi.test(devs[i].experience)) {
        prospects.push({
            phone: devs[i].phone,
            firstName: devs[i].firstName,
            lastName: devs[i].lastName,
            email: devs[i].email,
            socialMedia: devs[i].socialMedia
    }
}

Although both pieces of code do the same. There is a natural inclination to the first example. Maybe it's due to the explicit actions filter and map, which lower the bar to understand what the code does.

Using filter and map creates new arrays on memory by default, making it an inefficient solution when working with massive collections compared with the implementation that uses a for loop.

The above examples reveal a certainty regarding optimization:

There are always tradeoffs between readability, simplicity, and the optimal use of resources

The above statement explains wh refactoring and optimization compete to generate the best outcome.

It's up to you to decide based on the system, users, and developer's needs what aspect deserves more attention at a given time.

Free to decide or forced to comply?

A difference between these two concepts is when to pursue them.

Both disciplines are designed to solve someone's pain:

• 🔧 Refactoring solves the developer's pain of dealing with and working on complex code. In the long run, it prevents inheriting those problems to customers by making the system unreliable and unstable due to the difficulty of maintaining existing functionalities while adding new ones.

• 🚀 Optimization solves a user's or customer's pain. Another reason is to comply with an agreement between who provides the software and who's paying for it.

Refactoring problems are often more visible than optimization problems due to being interacting every day with the code. Still, since the latter affects people who are paying for the software, it has a higher priority in the majority of cases.

Affecting customers' work or not fulfilling contract clauses gives code optimization a whole different level of urgency.

Optimization is always made when required, not before, and involves a clear objective.

On the contrary, since refactorization is developers' problem (until is not), and their needs have a lower priority than business people, customers, and users, it's up to the team to explain the effort invested and decide when to do it.

Since time is money, and to avoid " convincing" non-developers that the teams need time to conduct refactors. A good option is to do these changes on every user story when they still involve a small effort and low risk.

It is like having a mindset of cleaning as you go.

Refactoring should be done frequently on every task, a little every time. That way, we ensure the refactor risk, cost, and effort remains low

Limited or continuous?

When optimizing code, we are clear on one thing: The desired metric's value.

Knowing the magic number doesn't tell you anything about achieving it. The team needs to brainstorm what to do, choose an idea and get hands-on to see if it works. If not, the process is repeated.

As you can see, achieving an optimization goal can consume a lot of time. One strategy is to limit the time spent on every idea to get a fast outcome. The team decides whether to invest a few hours or days per idea until the goal is eventually met.

Due to the complexity that represents reaching the magic number, never try to go beyond that, or you could find yourself in an impossible crusade.

Now, what about refactoring? I'll explain it through a hypothetical case:

Imagine that your code is a house, and every time you see something bad or that could be better, you represent it with a defect in the house. It might be a broken window, paint damage, a missing door...

(Source: Tim Arterbury, on Unsplash @tim_arterbury )

If you do nothing, your house will lose all of its value at some point.

But, if only you could repair immediately any damage by replacing the broken window, repainting the house, and installing a new door where it was missing. You'd be spending less money and effort to maintain the high value of your house.

The same analogy works with gardening. You must remove the weeds, move the earth, and water the plants, all of this regularly, otherwise, your garden will lose all its beauty, and in extreme cases, it can die.

Refactoring should be done regularly, like gardening. But keep in mind that plants are going to die either way if you're watering them once a month.

Refactimization or Optifactoring?

We know now that these disciplines are designed to address different purposes, and each one affects the counterpart.

Although you can benefit both by targeting the golden mean.

You can do some refactorizations without impacting the performance, like the one we saw at the beginning of this blog post. We can rename variables, extract methods, modularize the code, or remove duplicated code.

👩‍🏫 Example

2-dimensional arrays are a widely used data structure, also known as Matrix.

Images are often represented using 2-dimensional arrays.

For example, a picture of 1920x1080 has 1920 rows and 1080 columns.

1920x1080 = 2073600 cells!

Each cell contains a color represented in RGB (Red, Green, Blue) with a 3-tuple, the first value for the red channel, the second as the green, and the last as the blue. Each value could be between 0 and 255.

2-dimensional arrays are easy to understand by humans, but operations over these arrays tend to have an O(n^2) complexity. A linear approach O(n) would be better to reduce the processing time on large images.

A simple optimization is to encode the 2-dimensional array into a 1-dimensional by remembering the splits to identify cells as part of different rows within a single array.

Doing the above process every time we need to deal with images is challenging. In order to make the developer's life easier, we can refactor that code to hide the encoding process behind a class. That way, anyone using that class will think it is dealing with 2-dimensional arrays, but they won't know the story is different internally.

We offer specialized methods to retrieve each cell and perform common matrix operations in the class.

class SquareMatrix {
    private cells: number[] = [];
    private mColumns: number;

    // Encode Bidimensional array into a one-dimensional array
    SquareMatrix(arr: number[]) {
          let i = 0;
          let j = 0;
          while(i < arr.length**2) {
              if(j === arr.length) {
                  j = 0;
                  i++;
              }
              this.cells.push(arr[i][j]);
              j++;
          }

         // Since it's a square matrix the number of columns is the
         // same as the number of rows
          this.mColumns = arr.length;
    }

    public cell(rowIndex: number, colIndex: number): number {
         return this.cells[this.mColumns*rowIndex + colIndex];
    }
    /*
       .
       .
       .
    */
}

The end result is an optimized code that's readable and hide complexity through a public API (The class's public methods).

const matrixA = new SquareMatrix([
    [1,2,3],
    [4,5,6],
    [7,8,9]
]);

matrixA.cell(0,0) // 1
matrixA.cell(1,2) // 6
matrixA.cell(2,2) // 9

const matrixB = new SquareMatrix([
    [1,2,1],
    [0,1,1],
    [3,2,0]
]);

const matrixC =  matrixA.add(matrixB);

To simplify the example above, we assume that the encoding would suffice, but in a real scenario, we need to test the change and if it works, only then refactor. We can use the optimization metric to control the refactoring by knowing if we are getting worse than what we achieved with the optimization.

The other way around is more difficult because optimizing the software can diminish the refactoring benefits done, and we don't have any metric to know when that happens.

Conclusions

• Refactoring and optimization are not the same
• Both have different purposes, although they both change the code without changing the observed behavior
• In the case of optimization, users may detect something has changed because the application got faster or can handle more operations
• Optimization always has a deadline, and it's scoped while refactoring is up to the devs to decide when they should do it, although the best approach is to incorporate this discipline daily
• Both disciplines can be combined, considering that focusing on one will affect the other. It's a matter of finding the golden mean.
• A suggestion is to always apply refactoring at last. Because there are always changes to do that won't affect the optimization accomplished.

What happened? The restaurant wasn't full, the attention was friendly, but the order was wrong and delivered with a significant delay...

It was the kitchen!!

Apparently, they were too busy cooking and dispatching the orders that no one took the time to properly clean and replenish ingredients, causing a big mess with the service.

It could all have been avoided if the kitchen team had organized better to clean the tools and the place while others focused on preparing each meal.

💣 The total cost of owning a mess

As a developer, can you relate to the previous story?

If you've been coding for a while, something similar already happened to you. Customers mad because the team was taken too long to fix bugs or delivering new features, and internally everything was a mess, like in the example.

When we work on a project where the main goal is to deliver features as fast as possible or with unrealistic deadlines, developers start taking shortcuts to satisfy everyone with the results. We succumb to the pressure of managers, customers, and even colleagues. The team is too busy with unrealistic compromises, leaving no time to clean-or at least that's what we believe-, so we avoid it until one day we start noticing that we are no longer going as fast we used to.

When the team stops worrying about how complex the code is becoming, it's a matter of time until it reaches a state where it will become a complete pain to work with. Soon adding just one line of code will require an enormous effort.

Eventually, the internal problem will be reflected externally in:

1. Customer feedback: due to delays, poor quality deliveries, too many errors.
2. Lack of ability to respond quickly to events: Everything will require more time and effort due to how complex it is to continue working with the code.

Soon, productivity will drop, our customer complaints will rise, raising alarms within the company.

Once the project reaches that state of complexity, people will end up leaving the company, tired of working and maintaining a rotten code. In addition, the company will lose valuable knowledge and skills that took months, even years, to build.

Nobody wants to work with rotten code.

Developers will demand to drop it all ways and start over because it's no longer sustainable to work with that code. In the end, after lengthy discussions and multiple complaints, the company will acknowledge the problem and will be forced to drop the current project BUT not until the new project have all the existing features😭

Good code matters

Working with good code always matters, to you, to me, to everybody on the team, to customers and managers. Because if we can work smoothly, blazing-fast, and with less effort, it's a win-win situation for everyone.

The problem is that code has a natural tendency to get messy over time, which can be caused by many factors; some of the most common are:

• Having a system coupled to ever-changing technologies and dependencies
• Not following coding guidelines
• Taking shortcuts to fulfill customers or managers wishes
• The loss of knowledge due to the enter and leave of coworkers on the project
• Changes in the requirements

We call some of those causes accidental complexity; things just happen and affect our code. But, there is also essential complexity, which has to do with the intrinsic complexity of the problem we are trying to solve. For example, writing a personal blog is less complex than building an airline reservation system (ARS).

Nevertheless, an experienced developer can write simple, readable, easy-to-understand code no matter the complexity. Still, it's worth nothing if the rest of the team keeps adding sloppy code.

Writing good code is the responsibility of the whole team

How can we assure the code keeps clean if we are constantly adding more code?.

Simple. Making code improvement a frequent task.

🚁 Refactoring to the rescue

A good chef knows the importance of maintaining the kitchen clean and the tools sharp and ready. As developers, we should do the same to make our job a breeze.

In software development, the technique that helps us with that is called refactoring and one definition is:

Discipline technique for restructuring an existing body of code, altering its internal structure without affecting its external behavior — Martin Fowler

In simple words, refactoring is all about changing the code but not what it does. If the code was doing A, after the refactor should still be doing A, not A.1 not A + B, just A.

If we end up breaking something during refactoring, then it isn't a refactor; it's a rewrite of code. The same goes when we start including features that we never were included initially.

The objective is to make the code maintainable and extensible. We do it by simplifying the code; when the code is simple, it's easy to read, contributing to understanding it better. This is key in reducing technical costs because by working with simple and clean code, we face less resistance to changes accelerating the software development process.

Through refactoring, we make the developer's life easier; while the customers are unaware of the changes, they kept seeing the same product.

There is a downside, though. Because we are changing how the code is written, how it looks, and how it feels to works with it. There are many instances to screw it up in an epic way. However, the risks are proportional to the size of the refactor, so we should always aim to keep the changes as minimal as possible. One rule that supports this idea it's the boy scout rule.

🏕️ Boy Scout rule

Leave the campground cleaner than you found it

Whether you're working on an important feature or a critical bug, if you spot something that can be improved, do it.

With this in mind, refactors will be tiny enough to not represent a significant risk.

What then when I discover that we need a massive change? Do I pause my current task and start the tedious big refactor?

• Absolutely not

Big changes are consequences of bad decisions and require a ton of effort. It's more usual to face this kind of monster while trying to improve legacy code. In this case, notify the team, evaluate the impact and treat it like any other feature. Treat big refactors as the exception to the rule; in general, we should avoid scheduling refactors because we run the risk of never doing them.

If there is a chance to tackle the problem one little refactor at a time, do this instead.

You can think of refactoring as gardening, a set of essential and frequent activities to have a beautiful garden. Like with plants, we have to maintain our code.

✅ Benefits of refactoring

• It helps to simplify the code, making it flexible, easy to understand and to work with it
• It helps to keep the project updated with new technologies and standards
• It reduces waste by allowing us to delete unnecessary and over-complicated code
• It helps to keep the big picture of the project. By refactoring often different pieces of code, we refresh the idea of how those parts work

🏆 The outcome of refactoring

Even when there isn't an ultimate form of our code because it's in constant change, we should always strive to have a clean code as an outcome. Although this cannot always be achieved, which makes good code an acceptable viable option.

The difference between both is that the clean code is the end state of the code in a given moment; when you read it, you can't find a way to make it better in that specific moment. Whereas with good code, we acknowledge that it has improvements, but we could keep polish it.

Depending on our time availability, we can choose to keep a good code rather than seeking to improve it; those changes can be delayed without causing any harm to the team.

Seek progress, not perfection

Refactoring is the never-ending pursuit of having a clean project.

When we should refactor?

There are many reasons to get back to read old code and refactor it, but without a clear purpose, we could end rebuilding things, falling into premature optimization, violations of the YAGNI principle, or adding new functionalities.

Don't refactor if you don't have a clear purpose in mind

Refactoring is a means to an end, so we need valid reasons to justify doing it, and "I don't like Pete's code" is not a valid reason.

A powerful reason is to simplify the code because it has become an obstacle to work with, or the team has gained a deeper understanding of the domain and the tools being used that can help to reduce the complexity.

Other valid and more specific reasons are:

• Preparing the code for incoming breaking changes on third-party dependencies
• Improving extensibility to facilitate new integrations
• Reveal the intent of obscure pieces of code to identify security issues easily
• Remove clear violations to good practices

The best time to consider refactoring is before adding any updates or new features to the existing code. In those situations, it's good to return and read the code to evaluate if it's in good shape to use it as a base for the incoming changes.

Not having a clear purpose doesn't mean we can forget about refactoring. On the contrary, we should always keep looking for what to improve, trying to find that purpose.

Considerations before refactoring

How can we improve something that we don't know it's wrong?

To refactor code, we first have to build knowledge about good practices, principles, and techniques that can help us to write better code. That way, we'll have the tools to identify bad code and know how to improve it.

Refactoring can be a high-risk discipline due to changing the code and preserving the current behavior, but with control version tools and automated tests, it becomes a less risky operation. Although, there are still things we should be aware of before starting refactoring code.

1. Never refactor without automated tests. If you don't have tests, you lack the feedback to know if you broke something during the process. So abort the refactor and start writing those tests!
2. Never add functionality. As devs, we can be tempted to use the opportunity to add new functionality, but by doing so, we could be introducing undetectable errors.
3. Set limits to refactors to a file, module, class, etc.
4. Always work at baby steps . You get early feedback, it's easier to start over, reducing the chances of wasting time.
5. Back up every successful refactor using your control version tool once your tests are green.

The key is to have automated tests; that's the best way to ensure we are changing the code and preserving the behavior simultaneously.

Final thoughts

Refactoring is not an optional task. It's a matter of professional survival. If something hurts now, tomorrow it will hurt more, so pay special attention to the signs.

Develop the knowledge required to identify what is needed to do and trust your tests.

Embrace continuous refactoring to reduce the high risks of dealing with large refactors.

Do it often, with a clear purpose in mind, and focus on progress, not perfection.

Further reading

Fowler, M. (2018). Refactoring: Improving the Design of Existing Code (2nd Edition) (Addison-Wesley Signature Series (Fowler)) (2nd ed.). Addison-Wesley Professional.

Here is an excellent article from Tiger Abrodi about the learnings of the above book

Martin, R. C. (2008). Chapter 1: Clean Code. In Clean Code: A Handbook of Agile Software Craftsmanship (1st ed., pp. 1–15). Pearson.

Beck, K. (2002). Chapter 31: Refactoring. In Test-Driven Development: By Example (1st ed., pp. 181–191). Addison-Wesley Professional.

Feathers, M. (2004). Chapter 1: Changing Software. In Working Effectively with Legacy Code (1st ed., pp. 3–8). Pearson.

In movies, stunt doubles are hired due to their preparation for action scenes. Furthermore, they allow the movie's production to not depend on the actor to do those dangerous scenes, exposing himself to injuries that could affect the film deadlines and incur on extra expenses.

Hollywood actors and their stunts (Keanu Reeves, Andrew Garfield, Will Smith, and Jackie Chan 🤣).

Table of contents

• What are Test Doubles
• Types of Test Doubles
  • Dummy objects
  • Fake objects
  • Stubs
  • Spies
  • mocks
• Mocks aren't stubs
• Practice is different from the Theory
• Practical situations when Test Doubles could help
• Prepare your nose for the smells
• Final thoughts

What are Test Doubles?

Test Doubles, is a term coined by Gerard Meszaros (Meszaros, 2007) they are the equivalent of stunt doubles, but in testing. The context is different, but the idea remains.

💡 Replace the original object with a copy that looks the "same" but behaves differently

Unlike stunt doubles who replace the original actor in some scenes, we don't replace our original code under test; we replace its dependencies. More specifically, we are breaking a real dependency to use our Test Double instead.

Why do we want to replace the dependencies of the code under test?

Michael Feathers explains it well in his book called "Working effectively with legacy code" (totally recommended).

There are two main reasons to break dependencies in favor of testing: Sensing and Separation (Feathers, 2004, p21-22)

1. Sensing. We want to see what is happening inside the code. What values are computed, and what calls are made.
2. Separation. We want to separate the code from its dependencies because we can't even start testing due to multiple requisites to instantiate dependencies or because they take too long to be ready.

Types of Test Doubles

There are multiple Test Doubles, created for different situations. In this section, we'll learn them, their applications, and their characteristics.

Note: From now on, we'll follow the testing jargon, referring to the "code under test" which is also called "System Under Test" as SUT and to its dependencies as collaborators.

Dummy objects

Perhaps you've encountered functions or methods that require more arguments than we actually need for testing a specific logic path during a test, and to avoid errors when calling the function, we fill the spaces with null or empty objects. Those objects that we passed down to the function are called dummy objects.

Dummy objects are passed around but never actually used in the code; their only purpose is to prevent errors when we don't respect the function's signature.

We can use any type of value like numbers, strings, and so on, is not necessary to always use null objects;

Fake objects

Fake objects are usually objects whose implementation is written by us, just like our code under test. They are used to replace the original implementation because it's too slow or it cannot be called during the test.

For example, on some tests, devs write their own "persistence layer" to save data and use a hash map as an In-memory database instead of calling the actual database due to is much slower and will slow down the tests.

Fake objects are often used in pseudo-integration tests or to replicate effects that could be too hard to do with the real collaborators

The downside is that we have to maintain those objects and write tests specifically for their functionalities.

Stubs

Stubs are like a fake object but with no more than one line of code implemented: A return statement.

function stub(value) {
    return value;
}

They are used to return constant values, and _most of the times, they don't return anything

function theMostSimpleStub() {
}

function theMostSimpleAsyncStub() {
   return Promise.resolve();
}

Its main use is to direct code's execution and contribute to verify state changes in the SUT through the values provided by itself. Stubs guide the code execution path, providing the necessary values to enter conditionals (if and switch statements) or to continue immediately when the code reaches a blocking point, like waiting for asynchronous code to finish its execution.

Spies

Spies' purpose is to record the calls we made to a function or method. They are used to sense the behavior under test, to know if the functions are executed in the correct order and with the expected arguments.

They are stubs augmented, thereby don't execute the real implementation, and instead, they can return predefined values, but additionally, they act as proxies to record arguments.

Spies perform the same verification as mocks but with a different syntax. In both cases, we check the behavior rather than verifying if the resulting state after executing the SUT has changed.

There are two types of spies: Some are anonymous functions, while others wrap existing methods on collaborators

Mocks

Mocks are objects pre-programmed with responses but different from Stubs because they also contain expectations that work as contracts of the calls they are expected to receive. They have a verification phase where all the calls made to the mock are compared to seek if they match against the calls and arguments expected. In case of any inconsistency, mocks can throw an exception when they receive an unexpected call.

Mocks aren't stubs

Developers tend to relate the word "mock" to the general action of replacing real objects with special objects that mimic the structure of the original ones. As we saw before, we can use many special objects to achieve that, and not necessarily need to be mock objects; we can do the same with stubs. Because of that, sometimes devs, when talking about "mocks," are referring to stubs or spies without knowing it.

Mocks and stubs have similarities but also differences. The main one is that mocks set expectations for their future calls. That distinction creates a whole different way of doing testing.

When we use mocks, our goal is to test the code and know how it was executed; what paths it took, which arguments its mocked dependencies received, how many times those functions were called, and sometimes, even in what order were executed. By using mocks, we are doing behavior verification.

In contrast, with stubs, we fake values and method responses to drive the system under tests (SUT) execution, and at the end of the test, we check if the final state was the expected. By using stubs, we perform a state verification.

Mocks aren't the equivalent of stubs. They are similar but mocks enable a different style of testing.

Behavior verification, using mocks, changes the common anatomy of functional tests, altering how the tests are structured by adding new segments to set the mock's expectations and also requesting its expectations verification.

Nevertheless, we can also perform behavior verification without using mocks, but spies instead. With them, we can fake the implementation, set expectations to check the code to behave as we want, and all of that without changing the test structure because with spies, the verifications are writing at the end of the tests as we usually do.

So, you may wonder, why use mocks over spies then? Or why follow a behavior verification over verifying the state? I suppose it is a simple preference. In software development, we can do things in many different ways. Some devs prefer using mocks and other spies to do behavior verification. Others avoid faking dependencies as much they can and check the end state of each test.

Practice is different from the Theory

Although we have different Test Doubles defined, with their specific uses. Testing libraries difficult the task of identifying each one them, the line is blurred due to the lack of standardization regarding Test Doubles definition. In some libraries, multiple Test Doubles are hidden behind a single public utility function or not implemented at all.

Comparing Jest and Sinon

Dummy objects weren't included in the comparison because they are the easiest Test Double to create, and we don't require a library for that.

As you can see, in practice, each testing library uses its own definition of Test Doubles.

Practical situations when Test Doubles could help

• Test an error hard to trigger (e.g., memory overflow)
• File management
• Caching
• Third-party system integrations (e.g., email, databases, APIs)
• Fake services to test functionalities in environments where those services are disabled(e.g
  cell phone sensors)

Prepare your nose for the smells

Now you know what are Test Doubles, but I can't let you go without telling you the most important thing.

Test Doubles are a code smell!!

A code smell is not necessarily bad, but it definitely must catch our attention when reviewing the code. But why is that?

Let's see their benefits, with Test doubles we can:

• Run our tests faster
• Isolate our coupled code
• Corroborate logic by verifying Test Doubles calls while executing the SUT

Unfortunately, they also have disadvantages. When we create stubs or mocks we are faking an implementation, if we overuse them we could end testing nothing more than Test Doubles results and not the feature we intend to build.

Here an example, let's say we want to test a function whose purpose is to capitalize a given string. The function uses internally the capitalize utility from a third-party library called lodash .

import * as _ from 'lodash';

export function capitalize(str) {
    return _.capitalize(str);
}

Tell me, if we replace the _.capitalize function with a stub. Could that test tell us something useful? -- Absolutely nothing!!

However, if we prove that the _.capitalize function is called with the same input as our function, the test might be useful but it will be coupled to the library.

In this specific example, what we want is to know if our capitalize function returns the capitalized version of a given string. We can test that directly, and by doing so we free ourselves from lodash , allowing us to replace the library without having to change the tests if we want. The tests will fail only when the feature fails.

import { capitalize } from './text-utils/capitalize';

test('capitalize function should return the capitalized version of a given string', () => {
    expect(capitalize('testing is awesome')).toEqual('Testing is awesome');
});

We coupled the tests to the real implementation when we do a behavior verification using mocks or spies. If the system under test changes the calls of its collaborators, those mocks and expectations will fail, which isn't a problem when the code is used in one place, but if it's shared among multiple files, every related test will fail.

Behavior verification makes our tests brittle.

When the tests depend on how we call the SUT collaborators, it also affects refactoring. If the code change, it's more likely to break multiple tests even without changing the behavior (Refactoring doesn't change a feature behavior).

You must train your senses to know when is enough of faking dependencies and when we should use the real collaborators instead.

I can give you the last recommendation: never fake business rules, you can fake any other thing, but your core logic must remain intact. Favor testing with real collaborators when you test your core logic.

Final thoughts

Test Doubles have lots of benefits and are used by lots of developers, so it's a good use of time, learning about them. Besides their advantages, consider that they can also become a source of problems when we overuse them. Don't abuse Mocks, Spies, and Stubs

Knowing all the types of Test Doubles and their use cases can help you identify when to use them, but nevertheless, remember that testing libraries could have their own definitions. Therefore you must also learn how to implement Test Doubles using your testing library of choice.

Abusing of Test Doubles can make the tests brittle and can make refactoring a challenging task, also give a false sense of security; to avoid these problems, follow these tips:

• Use real implementations whenever you can.
• Write your software composing small pieces of code. That will restrict the need for fake dependencies.
• Use mocks and spies on external dependencies and not on core business logic.

Test doubles are required when we want to sense and separate our code during testing, a helpful characteristic on legacy code to match our test with already working behavior.

If we think about it, Test Doubles are more and more required as long as our code remains coupled, so if we focus on decomposing the code into smaller units, and we probably won't need to fake any dependency.

References

Meszaros, Gerard (2007, May 11). Chapter 11 Using Test Doubles. In Addison-Wesley; 1st edition (Ed.). xUnit Test Patterns: Refactoring Test Code

Feathers, Michael (2004, Sept 22). Chapter 3: Sensing and Separation. In Pearson (Ed.). Working Effectively with Legacy Code (p21-22).

Fowler, Martin. (2006, January 16). TestDouble. https://martinfowler.com/bliki/TestDouble.html

Fowler, Martin. (2007, January 02). Mocks Aren't Stubs. https://martinfowler.com/articles/mocksArentStubs.html

Sometimes we don't test things directly, but we adjust our behavior based on others' feedback, like reading a product's review before buying it on the internet.

We know about testing and feedback, but apparently, some companies and developers believe that they can skip that process as long as they deliver a working product.

They can't be more wrong...

A product that works is just the tip of the iceberg. Once it solves someone else's problem, it needs to improve its quality and be easy to maintain to secure its future; and even better when the product is built from the start on quality.

That's why developers who know how to write tests are attractive to recruiters, companies, and future team members because they can ensure quality, saving time and money.

If you don't believe me, down is the face of a Tech Lead interviewing a candidate who says he knows how to write automated tests 👇👇👇

What is testing?

Testing, or more formally software testing, is performed to ensure the software behaves as expected by putting the production code under different scenarios, conditions, and situations. It also works to discover any problem that the team didn't consider during the software's conception.

Although testing is a broader discipline that involves different roles, such as QA testers and software developers, in this article, we'll focus on what a developer can do to contribute to quality assurance.

What happens when we don't test our code?

The time to deliver software is shortened every day, meaning that we need to ship new features and reach competitors' delivery capabilities sooner; otherwise, we'll be quick-off out of the market. The situation left no space for errors. Therefore, companies prefer to invest in improving the product's quality before it gets to the user's hands.

The reasons can vary, but we could lose our customer trust because of having too many errors or be replaced by our competition by not shipping features faster.

Why manual testing isn't enough?

Although manual testing can help to increase the quality of a product, it has three main problems:

• Is NOT scalable
• Is NOT fast
• Is NOT repeatable

These problems come into account, especially when our software begins to grow; more lines of code result in a growing density of defects which increases the complexity of testing the product manually.

If the number of defects surpasses the QA team's capabilities, they will pass from a proactive attitude to a reactive one. If that happens, they will stop every improvement and future ideas, prioritizing the defects. The problem can also occur in teams where developers and QA testers collaborate in the same team.

The amount of people restricts manual testing. There are a limited number of tasks a human can take. If the number of defects is greater, eventually, those will pass to production and will have to be solved, cutting the amount of time to build new features and improve the code.

There are other problems caused by doing manual testing while developing :

• Create over-complicated solutions, unintentional: When we start immediately to work on something without considering how we'll test the code, we ended up with code that's hard to maintain.
• Requiring extra documentation to understand what to test: Most likely, only two people will know how to test the code, the person who wrote it and the QA tester, if he exists. To remove the authorship of code, the team will need to document the testing process so that anyone could test it in the future.
• Fear of refactoring: By not having a test to rely on, and execute whenever we can, developers will avoid improving, separating, and changing extensive code because of the fear of breaking something without knowing.

All of us do manual testing at a certain point. It's valuable to get visual insight and to discover flaws in the system by taking unexpected and crazy paths, just like real users do. To scale, we need to automate whatever we can, letting developers free of testing manually to focus on writing new features or improving the existing ones.

What is an automated test?

As you may guess, an automated test is a test whose logic has been automated through code.

It's a piece of code written with the sole purpose of testing our production code, the code that is going to be used by our customers and users.

** For the sake of simplicity and because it's widely used the word "test" to refer to an "automated test", we'll keep that correspondence on the rest of the article

Benefits of automated testing

• Tests work as a safety net to make changes (refactoring): Now we feel confident on changing code because if we break something our tests will warn us
• Tests can work as live documentation when they are descriptive enough: Additional to documentation files now we can read our tests to understand how the code works and access to useful examples
• Tests prevent wasting unnecessary time on debugging: Rather than spending time trying to figuring out what is wrong, we use the feedback our broken tests will give us. If we have a bug, we write a new test to expose the error
• Tests are the first users of our code: We can have early feedback from our code, even before running the code if we write the tests before the code
• Thinking in testing while coding can lead us to a better design: Now we write our code to make it easier to test, to do so we rely on design patterns and best practices to build a decoupled code

Here is a great article written by Mario Cervera to complement the benefits of testing.

Example: A simple automated test

Suppose we need to write a code to reverse a string. That function will be used in our production code.

As we already know, a test is just code. Therefore, a test for the reverse function could look like the following function:

import reverse from '../reverse'

function test(value, expected) {
    return reverse(value) === expected;
}

As we can see, a basic test just uses the real reverse function and compares its result against an expected result. We call that verification an assertion or expectation.

With our test function written, we can start adding more tests cases:

• Reverse function must return the same string if it's a palindrome

  test('level', 'level');
  

• Reverse function must return the inverted string

  test('amazing', 'gnizama');
  

• Reverse string must return an empty string when receiving an empty string

  test('', '');
  

Now, what if we also want the reverse function to throw an error when receives a null or undefined value?

How can we test that?

We'll need to modify our test function to support the new requirement in the reverse function, the changes that we need to include are:

• Accept strings and errors as the second argument, the expected result
• Catch any error thrown by the reverse function and compare its error message with the message of the expected error

With the new requirements in mind, the resulting code of the test function will look like this:

function test(original, expected) {
    if (expected instanceof Error) {
        return testError(original, expected);
    }
    return testString(original, expected);
}

function testString(original, expected) {
   return reverse(original) === expected;
}

function testError(original, expected) {
    try {
       reverse(original);
       return false;
    } catch(e) {
       return e.message === expected.message;
    }

With the test function updated, we can now add the new test cases:

• The reverse string function must throw an error when receives a null

  test(null, new Error('invalid value, expected an string'));
  

• The reverse string function must throw an error when receives an undefined

  test(undefined, new Error('invalid value, expected an string'));
  

Finally to know if the tests passed or not we will print the result in the terminal using the function console.log

console.log(test('level', 'level'));
console.log(test('amazing', 'gnizama'));
console.log(test('', ''));
console.log(test(null, new Error('invalid value, expected an string')));
console.log(test(undefined, new Error('invalid value, expected an string')));

After running our tiny script we'll see something like the following

Voila! We wrote our first test!. Although the feedback is really basic 🤔

How PROS do it?

Short answer, as we did in the previous section.

it was a joke, of course not

Remember that we said an automated test is just code? If the test is in charge of verifying the production code to work as expected, who checks the test to work as expected?

Our tiny test function from the previous example was so smaller that we could easily identify a problem with our eyes.

But, also remember that as soon as we added another possible outcome, passing from returning a string to throwing an error, we needed to adapt the behavior of the test function to support that change without breaking the test.

Every time we are forced to add logic into the test because of a concern that's different from testing the production code, like extending the available assertions, the risk of committing an error increases. Imagine adding asynchronous code, numbers, timeouts, intervals, objects, and so on. Now it doesn't seem to be so easy to detect problems on our tests.

To avoid any problem writing custom test functions, developers use libraries specifically designed to help writing tests.

Those libraries present utilities in the form of functions or classes to structure our tests, and that way, we focus on writing the logic inside. We can find them as third-party libraries or as a part of the programming language, like the unittest package in Python.

Other libraries help us to deal with assertions. They supply utilities to compare different types of values, partially match objects or arrays, match regular expressions, catching errors, handling promises, knowing the number of function calls, order of the function calls, and more. These libraries are called assertion libraries, and you can find them as a standalone library or as part of a whole testing framework.

In the above image Describe, it and expect are global functions set by the Jest library

In JavaScript, a standalone assertion library is chai whereas Jest includes its assertion utilities inside the whole framework.

There is another challenge when we write our own testing functions: we need a way to run the tests written in different files , because in a big project having everything in one file is not optimal. Therefore we will need a way to find those test files, run them separately from our production code_, perhaps also in parallel to optimize time spent and execute a subset of tests when we need to.

Fortunately, there are command-line programs that can solve the problems mentioned before; those programs are called test runners. In JavaScript mocha , jest and karma are test runners.

We can execute our tests from a terminal with a test runner, allowing us to run them in Continuous Integrations pipelines to validate the code before merging it.

As we see, testing libraries provide us all the power we need to focus solely on writing the logic behind our tests.

Oh!, and the feedback improves drastically using libraries compared with the test function that we wrote in the prior section.

How can we test?

1. Choose wisely the type of test

There are many types of tests, each one with different purposes and characteristics, but in general, we can classify them as functional tests and non-functional tests. The first exist to probe an expected behavior in our code, to check that what we coded is aligned with a functionality. The latter is for testing non-functional aspects of the system such as reliability, availability, scalability, and all the -ilities; they provide handy metrics to make data-driven decisions and to know when we need to optimize the code.

Functional tests provide us with feedback when working on the solution, while non-functional tests only after the solution worked, but it didn't satisfy a metric. Because of that, we'll likely have lots of functional tests and few non-functional tests in our project.

The reason behind having different types of functional tests (unit tests, integration, end-to-end) is that each one focuses on different aspects of our code, testing components in isolation, testing how they integrate together, or testing the whole application including UI.

Why are differences? Because when we require more integration(e.g., waiting until multiple services are up and running), the tests will be slower. With less integration, the feedback provided by the tests will be less confident regarding the whole system.

For example, let's said we are going to test a car's wheel, but we don't test if the wheel was bolted correctly to the chassis; even if the wheel passes its tests, the car could be bad ensembled because the wheel's tests don't tell us anything about it.

There is a concept called "The testing pyramid" used to balance how fast we get the feedback with how confidence it delivers us. The idea is to have as much as we can of isolated tests because they are faster and complement them with a few high-level tests involving multiples parts to test the application's crucial features and have high confidence.

2. Prepare the environment

After deciding which tests our system requires, the following questions can help us know more about what we need.

• Who will be in charge of writing those tests? Our team? another team? a QA team?
• The tests can be written completely isolated from the production code? Or do we need to have them as closes to the code we can to review the code and the tests together?
• Do we need to write the tests using a special syntax and file structure?

Answering the questions can guide us to decide whether we should write our tests in the same project or as a whole different project.

For example, End-to-End tests use UI elements to detect changes in the layout and navigate the application under test; they don't use the code!!. Therefore, we can write those tests in a whole different project, but if we have to maintain those tests, do we have enough people to handle another project?. A better decision could be to include them as a folder inside the same project as the production code.

Folder structure and file names for unit tests on JS and Python

Finally, we cannot forget to read the documentation of the testing library or framework that we chose. Probably they will be configured to search a specific folder structure, filename, or even syntax.

3. Anatomy of a functional test

Although there are different types of tests for various purposes, functional tests share a typical structure.

1. Import production code under test (not required in all the type of tests. e.g End-to-End)
2. Create a test suite (not required in all the languages neither libraries)
3. Write a test case
4. Write SetUp code
5. Call the production code
6. Assert the outcome

The above picture is a unit test, but the structure doesn't change too much in other functional tests. In each one, we'll have a setup to do everything needed to set the stage of the test case. Perhaps execute some actions or create data.

The setup can change from creating just objects to start up a database, create records on it, or even open a web page. The call to action could be a call to an API endpoint, and the assertion can be to compare if it has the correct status code.

How the structure is implemented can change from test to test, but its structure is more likely to remain the same.

How we arrange the code in a test?

Steps four to six receive different names depending on the type of tests, but all means the same. It is like telling a linear story.

• Introduction, Development, Conclusion
• SetUp, Call to action, Assertion
• Arrange, Act, Assert
• Given, When, Then

OK. They are great but, What about time? Will we go slower?

Yes, absolutely. At least at first, compared to not testing.

Every new skill requires time to develop. In this case, we need to change our mindset to start thinking about how the code we are writing can be tested. Also, learn to master the testing library or framework of choice.

At first it will appear that we are doubling our efforts by writing tests and production code. But, in reality, what was happening was that we were writing only half of the code required by not writing the tests.

To write tests should be seen as part of implementing the feature or fixing the bug

Writing tests doesn't mean we'll go twice as slow. After building enough experience, we'll write tests much faster. Besides, we'll write automated tests just once and update them only when the behavior they're testing has changed.

Automated tests offer quick feedback (between milliseconds and seconds) and the opportunity to execute the tests as many times as we want without effort. We get all the benefits of testing but with zero-waste.

By writing automated tests, we are betting on the long run; we seek stability.

In the end, it's a lot of time and money saved compared with debugging the code and having everyone busy handling defects without producing neither maintaining code.

If are so great, why some devs avoid writing automated tests?

-- Because it's not an easy task 😟

Many things make writing tests a complex task.

• Not having the knowledge
• Fear of experimenting in an environment full of pressures (overload of work or unreal expectations and deadlines)
• Not having the culture
• Having a code so coupled and convoluted that it's tough to add tests

Everything worth the effort will be hard to achieve at the beginning because it demands discipline and consistency.

Nothing is harder than working under a tight deadline and still taking the time to clean up as you go - Kent Beck, author of "Test-Driven Development by example" book.

Conclusion

Writing automated tests is a necessary skill that all companies need to adopt to scale and survive in a fast-paced industry growing each day.

Ensuring the quality of the products we build is a must to secure our customer's fidelity, and with the help of automated tests, we can do it without wasting the team's time. QA testers can use their time to automate and experiment proactively, and devs can use their time to build new features trusting that at any moment a test will break, delivering enough information to solve the problem as soon as something unexpected happens.

A good approach is to start with small, isolated, and fast tests. Then, complement with a few of slow and high confident tests.

Write tests using libraries and frameworks specifically designed for that. Also, organize the tests and code following their guidelines.

The whole idea of writing automated tests is to detect any defect immediately, moving the feedback more and more close to the development phase. But that doesn't mean we should discard manual tests completely; they are still a valuable tool for simulating unexpected user behavior that cannot be generalized either automated.

The most important thing is gathering courage and losing the fear of going slow initially but knowing that things will improve eventually.

What's next?

Thanks for reading until here. I hope I answered some of your questions, and much better if I raised questions you didn't know you have.

This is the first of many articles about software testing. I'll explain different types of tests, teach how to write them, improve them to have clean tests, teach about Test-Driven Development, and much more.

Finally, If you like, you can support me here 👇

• "Code needs to be self-explanatory"
• "Comments are useless"
• "Don't write comments in your code"
• "Comments are a code-smell"
• "Comments are an anti-pattern"

The thing is that writing comments aren't bad at all if you know in which cases they can help us and on which others they are a complete waste of time.

Code needs to be self-explanatory

Code should be expressive and intention-revealing. Needing comments to explain the code means the code doesn't describe itself well enough.

Our code is read far more times than is written, so we should aim to make it as easier to read as we can.

Sometimes it's clear when a comment is redundant.

// Calculate the square root of the sum of two numbers
const result = Math.sqrt(a + b);

// Timeout of 30 seconds
const timeout= 30000;

But other times, knowing if the use of comments is a good or bad idea, is confusing.

Consider the following example:

• Can you know in less than ten seconds, what the code does without reading the comments?

/*
* Calculate the total amount to pay for a pizza going through each
* item in the order and obtain the cost of each ingredient of the
* price object searching by section and ingredient name to then add 
* each subtotal and return the total to pay
*
* @param {object} o: pizza order
* @param {object} p: ingredients prices
* @return {number} total: total price to pay for the order
*/
function total(o, p) {
    let total = 0;

    Object.keys(o).forEach((key) => {
        if (key !== 'ingredients') {
            total += p[key][o[key]];
        } else {
            o.ingredients.forEach((value) => {
                total += p.ingredients[value];
            });
        }
    });

    return total;
}

In the above code, we used JSDocs, which is a fancy way to create documentation automatically by reading the comments and special tags like @ param or @ return that specify the parameters and the value returned by each function. Although JSDocs has justified use, when used for the sole purpose of describing what the code does, it becomes useless.

We can refactor the previous example using descriptive and meaningful variable names, moving some logic to a smaller function so that its name explains what the function does. After that, we will soon realize that all such comments are unnecessary.

function calculatePriceToPay(pizzaOrder, tableOfPrices) {
    let totalPrice = 0;

    Object
        .entries(pizzaOrder)
        .forEach(([section, item]) => {
            totalPrice += getItemPrice(section, item, tableOfPrices);
     });

    return totalPrice;
}


function getItemPrice(section, item, tableOfPrices) {
    let price = 0;
    if (Array.isArray(item)) {
        price = item.reduce((accumulator, subItem) => {
             return accumulator +=  tableOfPrices[section][subItem];
        }, 0);
    } else {
        price = tableOfPrices[section][item];
    }
    return price;
}

The only reason to hesitate before removing those comments is if the JSDocs is actually been used to create documentation, if not, or if they were another type of comments we could remove them immediately.

See?. The calculatePriceToPay function is much simple to read after the refactoring even without the comments.

When we write code with intention revealing and easy to understand, every previous comment whose sole purpose was to explain the code, lose completely its value, and therefore we can remove it

Avoid using comments to explain "What"

Whenever you find comments used to explain what the code is doing I invite you to question if they are really necessary because in the majority of cases those comments aren't needed, and can be deleted.

We should understand what the code is doing after reading it line by line and not by reading a description.

Another reason is that code is alive, it changes more frequently than comments and even documentation, so it's more likely to see comments become obsolete sooner than you think.

As in everything, there are exceptions. There is one case in which we can use comments to describe the code; If we are building a really complex algorithm or performing complex operations, in non-trivial domains like statistics, physics, chemistry, healthcare. In those situations, we can give additional context and reinforce the self-described code through the use of comments.

Let's see an example:

 import math

EARTH_RADIUS_KM = 6371

def get_distance_km(src_lat, src_lng, dest_lat, dest_lng):
"""
Calculate the linear distance between two points in the earth using
the Haversine Formula

The points are GPS coordinates with a latitude and longitude 
represented as floats numbers
"""   

    DEGREES_TO_RADIANS = math.pi / 180.0

    # Convert latitude and longitude to
    # spherical coordinates in radians
    phi_src = (90.0 - src_lat) * DEGREES_TO_RADIANS
    phi_dest = (90.0 - dest_lat) * DEGREES_TO_RADIANS

    theta_src = src_lng * DEGREES_TO_RADIANS
    theta_dest = dest_lng * DEGREES_TO_RADIANS

    # Compute spherical distance from spherical coordinates.
    cos = (math.sin(phi_src) * math.sin(phi_dest) * math.cos(theta_src - theta_dest) +
           math.cos(phi_src) * math.cos(phi_dest))
    arc = math.acos(cos)


    distance_in_km = arc * EARTH_RADIUS_KM

    return distance

As you can see above, even with a clean code, it's difficult, near to impossible to understand what the code does. Why is that?, It's because it requires domain-specific knowledge. The variable names represent mathematical symbols and formulas but none of them give us context to understand what those formulas are needed, the use of comments, in this case, guides us through the steps and delivers us additional context.

With the use of those comments, we can quickly search on google for "Haversine function" and "spherical coordinates" to get the missing information.

Write comments to explain "Why"

Comments are a great tool to explain things that cannot be explained through the code.

They are good for express the reasons behind our decisions and provide additional context.

• Why we write the code in this way?
• Why we took that decision?
• Why we are using this library?

Cases where is a good idea to use comments:

• Add links to issues that are affecting our code

  // Needed to handle Webpack and faux modules
  // See https://github.com/fastify/fastify/issues/2356
  // and https://github.com/fastify/fastify/discussions/2907.
  

• Explain exceptions to our code style

  // Typescript quirk - libraries exported with `export = ` need to be imported using `require()`.
  // See: https://github.com/microsoft/TypeScript/blob/master/doc/spec.md#1135-export-assignments
  import chaiShallowDeepEqual = require('chai-shallow-deep-equal');
  

• Redirect to an external source of information

  // Override timezone formatting for MSSQL
  // link: https://stackoverflow.com/questions/47056395/how-to-pass-a-datetime-from-nodejs-sequelize-to-mssql
  

• Justify our choices when writing the code

  // Some errors contain not only line numbers in stack traces
  // e.g. SyntaxErrors can contain snippets of code, and we don't
  // want to trim those, because they may have pointers to the column/character
  // which will get misaligned.
  const trimPaths = (string: string) =>
  string.match(STACK_PATH_REGEXP) ? trim(string) : string;
  

• Build automatic documentation

  /**
  * Initialize a new `View` with the given `name`.
  *
  * Options:
  *
  *   - `defaultEngine` the default template engine name
  *   - `engines` template engine require() cache
  *   - `root` root path for view lookup
  *
  * @param {string} name
  * @param {object} options
  * @public
  */
  

• Prevent unexpected errors by providing warning messages

  // This file is autogenerated by build/build-validation.js, do not edit
  

• Explain business decisions

  /**
  * This module contains code that will be migrated into 
  * its own service
  * DO NOT ADD MORE CODE INTO THIS MODULE
  * see epic: https://jira.example.com/browse/PM-32145
  **/
  

What comments should we avoid?

Comments can lie, that is a fact that can create confusion because, unlike code that keeps evolving, comments are rarely updated because it's not our priority as developers

In addition to redundant comments, we should avoid those that are implicitly or explicitly time-limited.

For example, the famous TODO or FIXME comments are used to let everyone know that there is a debt in the code that we must pay in the future, but the future could never come, and no one will review the code when the team needs to prioritize work. Instead of those comments, create a task in your task manager and label it "Technical Debt" to track how much debt the project generates and how much is paid in each iteration.

Conclusion

Comments are just another tool to solve a specific problem. The problem here is the lack of understanding after reading our code.

They aren't the bad of the movie, but they can become a waste of text so it's important to know when they are beneficial and when using them is nonsense.

As a general rule, write comments when you need to provide additional information that cannot be expressed through clean code.

If you like the article and want to support me to write more content like this

Don’t you think that five days is too much time to finish just one endpoint?

I Immediately react, trying to justifying the time invested, perhaps so fast and in a high tone that my boss thought I was furious and tried to calm me down. He starts saying that he doesn’t enjoy making me work until late, neither in my day off (yup, I wasn’t supposed to working that day; it was an earned day off). He says that we were doing something wrong, and in the retrospective, we’ll together discover the causes with the team.

After the phone call, my impression was that he doesn’t know how difficult the problem was and all the team’s effort to recover us from a delay caused by the client’s changes at the last moment. That day the sprint review went all right, the project manager from the client side was pleased with our work, but the problem wasn’t him otherwise their boss. Until the call, we always had been thinking that we were doing right. These thoughts explain why it took the whole team and me for a surprise to know that our client wasn’t satisfied with our performance.

The day after the call with my manager, I decided to try his words, and after thinking about it, I started to believe that maybe he was right. We were doing something wrong because the time wasn’t enough to finish our work even with all the team’s extra effort. We end it up moving the retrospective to the next day. On that morning, we receive a mail from our manager moving the meeting to another hour because he wanted to participate. When I saw the reactions of my teammates, well, there wasn’t much enthusiasm about it. So, because I was preparing myself to talk about the problem, I volunteered to lead the meeting and do the Ishikawa’s diagram to discover the causes of our client’s wrong impression of us. After a very long meeting with a lot of collaboration and constructive discussion, we came to this.

It resulted in many causes that influenced our client’s perception. Some of them were poor communication, lack of information to start the sprint, changes introduced after planning, lack of crucial processes, and external factors not considered when planning. We recognize that all these problems came from a bad implementation of Scrum. It was the first time we used this framework. Without proper training, it would likely look like a Zombie Scrum implementation with many anti-patterns.

As a team, we resolve to implement two solutions: one in the short term and the other in the long way. In a short time, we made an extraordinary deploy to production to accomplish the client release date. After that, we set some actions to correct the remaining problems in the next few sprints.

Here are the actions that we implement and the learnings that we gain

Know what they want and let them know what you need

In the scrum framework, this is called the definition of ready. It means that the requirements to develop a user story should be identified and completed before starting to work on it. For example, we can’t start working on an endpoint that should use the client’s database model -given by them- without knowing the details of the model, the business meaning of the tables and columns, ordering, possible filters, and so on.

When you have identified these requirements, ask for them, be clear and set a deadline to the client, explaining that if they don’t meet the deadline, the user story will be re-prioritized and excluded from the following sprint. All this was made at the refinement meeting when we revisit some stories to polish their definitions and identify dependencies between them whenever possible. Also, discovering the development tasks needed to accomplished the story.

Anticipate to changes, communicate at a fast speed when things happened

Sometimes the client isn’t clear about what user stories prioritize to develop them on the next sprint and change his mind barely hours before the start. One strategy to prevent this is to have the backlog updated and estimated with user stories to add and swap from the suggested sprint. That way, we can give the client the flexibility he needs to prioritizes according to the results and past events. There were other cases when the stories that were planned suffer changes in their definition or something unexpected occur that requires immediate attention and we need to include it in the sprint. Thus, it’s crucial to inform the team when these cases arise and update stories and acceptance criteria to reorganize the active sprint.

Have the backlog updated and estimated with user stories to add and trade from the suggested sprint. That way, you can give the client the flexibility he needs to prioritizes according to the results and past events.

It’s essential to back up every change and agreement made with the client. Do this via email and copy it to every stakeholder for transparency, indicating the changes’ impact and how the development team will act according to these changes. Explain to the customer when a delay may happen because of the changes and advise him when to stop adding, updating, or removing stories. Additionally, it’s crucial to explain what they can exchange from the current sprint to include new stories; ideally, it should always be work equivalent in effort.

There is always space for improvement: Optimize your development cycle

When your clients think that your team is slow, it’s related to three main problems:

• Bad communication
• Unoptimized workflow
• Unattainable commitments

They don’t understand what you are doing or how you do it, so you have a communication problem. Also, maybe you aren’t satisfying the client expectations about what should be delivered and when; this could be caused by an unoptimized workflow or setting higher expectations that you cannot accomplish (unattainable commitments problems).

Having and unoptimized development workflow is a tough one because even by resolving it, you can’t be sure that your client will change their mind if you keep setting unattainable commitments.

Optimize your development cycle and search for dead spaces in the sprint. Understand why team members are waiting until someone finishes a story needed to start working on their own stories.

Invest time on:

• Implementing CI/CD
• Test automatization
• Refine stories until you have almost only independent and small stories.
• Increase the coverage, boost the confidence to refactor the code
• Refactor what you can to allow easy extendability and maintainability.
• Reduce loss time, use contracts, and API specs to split the development so that nobody has to wait until others finish their work. (try swagger virtualization). Keep an eye on the number of dependant stories in the sprint. It could mean that the team is planning badly.
• Revisit your git workflow and implementation. Maybe it isn’t the most suitable for this project.
• Search for tools to increase the team’s productivity: code generators, CLI, libraries, packages, frameworks.
• Begin to measure; the time to finish stories, how many times a story is blocked, occurs unexpected events that affect development?. Then set actions together on every retrospective to eliminate the bad behavior and maintain good practices.
• Reduce the batch size of the sprint. That way, you reserve free space for unplanned work.

The primary purpose is to gain more time through automation and use that time on any unplanned work during the sprint. Also, keep watching any constraints to avoid possible bottlenecks on the sprint.

There is always room for improvement, so you must increase team efficiency to be effective. After eliminating one of the reasons why the team is considered slow, you’ll see a boost in productivity but beware of unattainable compromises. Measure the velocity and capacity of the team, explain it clearly to the client before building the next sprint, and remember never to plan above the maximum capacity of the team, or you’ll continue losing the client’s faith for not meeting your commitments.

Be the technology expert: Explain your development workflow to the client

Even these days are companies that don’t know how software is made, perhaps because they don’t need to know to use it. But, it’s valuable for the team that your client knows this type of information. It can help to understand why you make some decisions or why it’s too challenging to build something in a short period.

As a software engineer — or any equivalent role — It’s expected that you identify obstacles and risks to develop an application or system. You and your team are the technology experts, so behave like that and express your thoughts, emphasize what is essential and crucial to do for the project’s sake from a technological perspective. Also, inform the consequences of sacrifice quality against velocity. Even if you don’t work for an external client you are the technology consultant for the company that hires you.

Some clients have an IT area and maybe they do things faster than your team. But that doesn’t mean they do it right, this way of thinking can be easily changed when you explain why there is a development process with defined stages and what does every step in the process. Why you expend time writing tests or why sometimes is necessarily doing a refactor before adding new functionality.

The trick is explaining to your customer that they are paying for a product that is expected to be durable, that should fulfill a necessity, and to do so you need to focus not only on building new features fasts but also on doing it right. It should be a concern no only to make the software but also to prepare it to be easy to maintain, that way, it remains valuable for a long time and at a low cost.

Build a trustworthy relationship by improving the communication

One of the main things that helped us to change our client’s perception was to improve communication. We increase the dialog through phone calls and emails and always show them respect and a complete compromise to do our best for their product. But, there is a difference between making our best effort and do everything right. Sometimes you can commit errors and accidentally delete the client’s data or take down a reviewed service during a meeting. These things can happen all the time, and rather than trying to hide our blame someone else, it has more value to be transparent and honest.

There are plenty of companies and professionals capable of doing the work that your client needs, so always focus on building a trustworthy relationship; this adds value on top of high-quality products and is an advantage over your competition.

Mistakes are hidden opportunities to win the confidence of your client, all depends on how you approach them.

If you commit a mistake, don’t worry. Tell your client the situation and explain the options to solve the problem, also design ways to ensure that it will not happen again. The same approach can be applied when there are delays in the planning, raise your hand early to reveal what happened, and what should be the actions to prevent these delays.

Now, continuing with the story

In the next sprints, we apply and keep track of all the actions described above. We deliver more without sacrificing the quality by organizing the stories better and improving the timing between requesting the required information to start working on a story and added into a sprint. Also, we increase the messages in the communication channels and transparent any problem or external events that could affect the planned work.

We change our mindset from following the client’s indications without arguing to proposing better approaches and solutions to their product.

We notice changes in the attitude during the sprint reviews. The product manager and the manager itself -from the client-side- start to give us compliments about our work. They were genuinely impressed with the quality and the compromise of the team. They tell our manager that they were astonished about the team performance and velocity; they appreciate the effort and are glad for the results.

The changes that we implement helped us to make an impact on our relationship with the client. Now they understand and also believe in our way of work, all because of the outstanding results. In the final weeks of the project, they only call our boss to compliment and coordinate new opportunities for working together.

With all the team’s compromise to implement the actions described in this article, we manage to deliver a high-quality product that satisfies our client’s needs and changes their opinion about us.

The process described here is summarized in the diagram. It’s an iterative process in which we first use a neutral approach taking all the complaints to analyze them and discover insights that tell us what we are doing wrong. Then we set actions to correct bad behavior and improve the good ones. The most significant change introduced was to invest time teaching and educating our clients to know how we work and the benefits of our methodology. To keep the whole process sharp, we keep track of every experiment and action defined through metrics. That way, we know what is working and what should be corrected or discarded.

Perhaps the process described here is not suitable for your problems, and even if it does it, you may not have the same results with your clients.

Remember that every client is a different world, and for some of them, it is more important to meet a deadline rather than have a fully tested, robust, and reliable system.

You should invest time talking with your clients to know what their worries are. Usually, a product owner knows these things but is vital to transmitting to every team member to be aligned and on the same page.

We went through everything due to Scrum’s poor implementation and not having the proper knowledge, neither a coach nor a scrum master. Getting out of that situation was very difficult, so I suggest starting well and hiring an agile coach or an experienced scrum master to teach the principles and values ​​to all those involved in developing the product, but most importantly to the non-developers. Your team will save a lot of headaches if you can count on that support.