DEV Community: Joel Louzado

Level-Up as a Developer by Working with Legacy Codebases

Joel Louzado — Wed, 06 Dec 2023 06:58:52 +0000

Here's a list of topics and resources to use the next time you have a little down-time. Applying these skills will help you write more maintainable code. Over time you will also gain a reputation for being the kind of developer people turn to when they have a thorny problem to solve.

Functional Programming Basics

Functional Programming is a vast subject, but you can start to see benefits from the understanding of a single concept: Pure Functions. Let's start with a simple definition 👇

Pure vs Impure Functions in Functional Programming – What's the Difference?

Pure functions and impure functions are two programming terms you will often see in functional programming. One core difference between these two types of functions is whether or not they have side effects. In this article, you will learn what side effects are and we'll discuss the differences between pure

freecodecamp.org

This next video👇explains how to use it in your software.

Note: He refers to pure-functions as "calculations" and side-effects as "actions", so keep that in mind.

You will only learn by doing, so if you'd like to practice:

Go through your current code-base
Look for a Function where the side-effects and business-logic are mixed together
- ideally you already understand the details of the function really well
Separate out the Business Logic into a Pure-Function with just the "Calculations", and keep it separate from your side-effects.
- Ensure your application still works.

If you would like an example, here's code for an example ShoppingCart Class where you can add items and a discount is calculated before checkout:

Why would you want to do this though.

Most bugs tend to be in the Business Logic
If a Function or a Class logs to a DB or sends an email every time it's run, it becomes harder to test properly.
If you can extract a Calculation into a Pure Function, it becomes easier to run.
The easier it becomes to run, the easier it is to fix bugs.
You can even write unit-tests for your Pure-Functions and run them automatically on every change, making it easier to catch regressions.

Next Steps

There's a few other skills I think make it easier to work with old code, I'm going to add those in shortly:

TDD, for better-quality pure-functions
C4 Architecture Diagrams, for standardized documentation
Sequence Flow Diagrams in Mermaid, to get quicker feedback on code
Trunk Based Development, to reduce operational overhead for small teams
CodeScene, to manage the health of a codebase and pay-down tech-debt
Approval Testing, when the original devs on a project aren't available

Leave me a comment or DM me on Twitter if you have any specific requests or questions.

Publish to Dev.to via RSS

Joel Louzado — Tue, 02 Feb 2021 13:27:02 +0000

Ignore this one for now dear reader, just testing out the publish via RSS feature. 🙏

Here's a cute puppy for your troubles:

Create a "Series" from Markdown Editor

Joel Louzado — Tue, 02 Feb 2021 13:23:03 +0000

This is not anything new, but the instructions are a bit buried so I'm hoping that this write-up saves the next person the "duckduckgo-ing" and comment-reading I had to do.

First, what are we talking about. By Series, I'm talking about the badge that appears at the top of certain posts. For example, take a series of Book Notes by @danlebero the top of each post is decorated with links to the other posts in the series:

If you want to create a series, you can do so using the "Rich" editor as shown here:

A short guide on how to “make” the series widget on DEV

Dzhavat Ushev ・ Sep 27 '19 ・ 2 min read

#meta

Unfortunately, once you set the series value via the rich-editor, it won't switch back to the Markdown editor even if you revert your settings. I quite prefer the writing & thinking in markup so this was quite a deal-breaker for me.

After hunting around the comments, I found the answer in the last place I'd look: The User Manual, in the Front Matter section. Here's what the meta-data for this post looks like:

--------
title: Create a "Series" from Markdown Editor
published: true
description: You ever wondered how people are creating a series of posts here on dev.to? Wonder no more
tags: howto, tutorial, guide
series: "Publishing on Dev.to"
--------

Basically, you just set the series key in the header and the new post gets added to the series.

Thank you for reading, let me know if this works for you and give it a ❤️ if it saved you some time so it's easier for others to find it. 🙏

Can Spaced-Repetition help improve your Retrospectives?

Joel Louzado — Mon, 04 Jan 2021 10:58:48 +0000

I think most people would agree that Retrospectives are a vital part of building a high-performing team and yet it's often (in my experience, at least) rushed so that the next Sprint can begin. If your team is already having healthy discussions during your Retrospectives then you're winning, but if the same kinds of errors happen Sprint-after-Sprint then maybe the Retro itself needs some improvement.

With this post, I'm hoping to show that with a relatively small change a team can get a huge amount of value from the time they spend in Retrospectives. You're probably already capturing issues and ideas, from there it's about optimizing how they're evaluated and turned them into habits with the least wastage. If the system can also highlight successes as they happen that would be amazing!

Minimum-Viable Retrospective

In my experience, a good Retrospective balances two categories of items:

Previous Ideas, which will all be in various state of adoption, and
New Issues which are coming up all the time and need to be analyzed

We want to give both categories the appropriate time, without having to discuss every item in every meeting. In other words, it's about managing the team's attention.

Spaced-Repetition is an Attention-Manager

A very popular technique for studying is to use Flash Cards in combination with Spaced-Repetition. The standard-version (also called the Leitner Method) can be implemented with physical boxes and cards as follows:

Take a number of boxes (about 7)
- or one big box, with some separators. You get the idea.
as you're learning a new topic, make flash-cards for things you want to remember
put the new cards in the first box.

Next, when you sit down to study, review each box half as often as the previous one:

the first box gets reviewed every day,
second box gets reviewed every 2 days,
third box gets reviewed every 4 days,
and so on.

For each card, test yourself if you still remember it:

If you got it right, move the card to the next box
- from the second box to the third, for example
if you got it wrong, move it all the way back to the first box.
- sorry, I don't make the rules ¯_(ツ)_/¯

The reason the review-interval doubles each time is because with each subsequent reminder the brain retains the memory for longer before it starts to fade.

After 3 or 4 revisions your brain gets the message and realizes that it's something really important, and so it gets committed to memory.

An Organization is really a bunch of Individuals, so the collective memory is only as strong as that of the weakest link. We can use the same system of Spaced-Repetition to automatically trigger a "remembering" of an old improvement and help a team to turn it into a habit much more easily.

Applying Spaced-Repetition to a Retro

This could be implemented with the same boxes and cards we've just seen, but if you're already using a tool like Trello you can use that as well. If you would like a ready-made template you can click here to see an example.

Setup

Add the following columns:

CONFIG (where we'll set up our automation)
Pending Review
Review Weekly
Review Fortnightly
Review Monthly
Review Every 2 Months, etc

Add the Repeater Powerup and set up a Marker that automatically tells you which Columns are ready for review:

Each column needs one Marker, which could just be a card that says Review Me!!
Open the card, and click Repeat so that it gets repeated either weekly or fortnightly or whatever.

Refer the template if you want to see an example.

We're assuming here that your Retrospectives are run once a week. If not, adjust the automation and the columns accordingly and keep in mind that each subsequent column should get reviewed half as often as the previous one.

During the Sprint, team-members add items to the Pending Review column

First 25% of the Retrospective

When the Retrospective starts, collect any and all items that people want to discuss and put them in the Pending Review column. The items in the first column are probably the newest, so they'll probably take longer to discuss:

Let's say a card in Pending Review reads: "Lots of bugs are being released to Production".
The team decides it's time to introduce a Code Review Process.
Make a new card titled "Code-Review every PR before merging it" and move it to the bottom of the Every Week column.

Remainder of the Retrospective

For the remaining lists:

For each card, ask the question "Did we remember to do this in the last Sprint".
If YES, move the card one column to the Right.
- For example, if the card was in the Every 4 Weeks Column move it to Every 8 Weeks.
If NO, move the card all the way back to the first column (Every Week)
- if a card is repeatedly falling back to the first column, maybe move it to Pending Review so it can be discussed
- maybe the solution needs to be tweaked so that it better solves the problem
Archive the Marker once all the cards in that column are done

Benefits

After a Sprint or two you should start to see some positive changes:

Issues are raised more contextually because there's a way to gather them continuously throughout the Sprint.
Meta-discussion during the Retrospective (especially about which Items to discuss should go down)
Issues that get sorted out quickly become a highly-visible source of accomplishment so that the team can also see that progress is being made.
Onboarding becomes simpler because the team's working-style is automatically getting documented as it evolves.
- If anyone has a new idea they can also go back if anything similar has been tried before

Summary

If you're setting up a brand new team from scratch, I'd recommend Toyota Kata and Retrospective Antipatterns as starting points. The approach that's shared here is more to help existing teams that are feeling stuck to give their Processes & Thinking a bit of a shake-up.

So what do you think? My thoughts on this topic are still evolving so if you enjoyed it or would like to discuss, I'm at jlouzado on Twitter; that's probably the best way to reach me.

Thank you so much for reading, see you in the next one. :)

Acknowledgements

Nicky Case for creating how to remember anything which was my first introduction to Spaced-Repetition
- also the source of the screenshots used in this article
Andy Matushak's musing on Programmable Attention which inspired this implementation, and
Dan Lebrero and Tushar Mathur for reviews and advice on early drafts
Cover by Braden Collum on UnSplash - Runners in a race

Do Stacked-PRs require re-review after merge?

Joel Louzado — Sat, 14 Dec 2019 06:06:17 +0000

Scenario

I'm working on a big feature that I know can be broken into two parts
- these parts are, as is often the case, dependent on each other.
I branch off master and create branch feat/part1
I finish coding part1, and create a PR with this branch
- feat/part1 -> master
- this is PR-1
While I'm still checked out in feat/part1, I create a new branch feat/part2
I finish coding part 2 and create a second, "stacked" PR
- feat/part2 -> feat/part1.
- this is PR-2

Let's say both PRs get reviewed and approved. I now merge PR-2.

PR-1 now contains all the changes.

Question

Can I assume that PR-1 is now approved and merge-able or do I need to re-review it?

Background

As for why someone would do this, this technique of breaking up PRs is a way to breakup large changes into more manageable chunks
That way the rest of the team can give feedback more easily.
Can read more about it here: Stacked PRs To Keep Github Diffs Small | graysonkoonce.com

How would you manage spell-check of packages?

Joel Louzado — Wed, 30 Oct 2019 13:58:33 +0000

My npm package has custom words that trigger spell-check alerts unless whitelisted. I can add a whitelist for the cspell on my machine, but will everyone who imports my package need to do the same as well?

How do I make life easier for someone who installs my package as a dependency.

Your Unit Tests Should Be Immutable

Joel Louzado — Sat, 30 Mar 2019 14:01:38 +0000

Picture this...

Your project has been following TDD from the very start
You're tasked with refactoring a function (to improve performance, say)
You make a relatively minor change, and run the tests
Your tests for that unit pass, but then a bunch of unit tests in some random component fail!
- "What the hell is happening, these components aren't even related!" I hear you say.

To fix it you will need to change those tests in those unrelated units, and that's a big problem. Your tests need to be immutable to refactoring and the above scenario is a Test Smell.

Why is this a problem?

There are lots of benefits to TDD, but one that doesn't get as much airtime is that:

A good test-suite gives you confidence about the behaviour of your system.

However that confidence is NOT guaranteed by tooling, it comes from the fact that you followed TDD. You wrote a test, it failed, then you wrote some code and it passed. Therefore, that code works.

That means that the only reason you trust your codebase is because you trust your fellow developers to have also followed TDD. Which is to say, that relying on your test-suite is not a matter of Fact, but a matter of Trust.

Hence once a test-suite exists, we need to protect our Trust in it by minimizing changes to it.

Coming back to our hypothetical situation from earlier, Refactoring (by definition) is not supposed to be a change in behaviour. If you're now forced to update test-code in unrelated units, you now need to manually validate those units and (all their usages) before trust is restored in the system.

Reasons for Problem

For example, your unit originally set an internal state's canProceed and you refactored it to shouldProceed. These other units are failing because they were asserting on the value of canProceed.

If you go into those failing tests and update the tests with the new assumption it's highly likely that an error will get made and you might assert false instead of true or any number of other issues. You might even accidentally delete a test (in more complex scenarios). The worst part of it is that your test suite can't save you from these mistakes because it can't self-test; the Light going Green doesn't mean anything if the test implementation is giving you a false-positive.

Desired Behaviour

The only reason to change a test should be if the required behaviour of the system changes. Either:

There's a bug in your implementation that you need to fix, or
There's a requirement that's a breaking change

Tests don't guarantee bug-free code, they're about enabling faster feedback.

In all other cases, we expect the tests to be Immutable i.e. Refactoring should not require a change in tests.

Achieving Test Immutability

Since we don't have a test-suite for our test-suite, there's increased pressure to follow clean-code guidelines while implementing it. Once tests are written the intention is that they should be encased in ember, so we should aim to get it right the first time.

Here are some suggestions:

Name your tests explicitly

Bad: test('should set correct headers')

Good: test('should set the 'device' header to 'mobile')

If you're writing the test name and it's running a bit lengthy, you might be trying to test too many things or might have too many state-values to list out.

That's okay, favour an explicit name over a short sentence. Atleast it's clear. And anyway, you can fix that in the next point.

Use Domain-Language while naming your tests

Use terms relevant to your users

Bad: $1.00 - $2000.00 = No Interest
Good: Loans of $2000 and below are interest-free

Describe expected behaviour in the test name, rather than in the `expected` result

Passable:

test('$2001.00 Loan Amount', () => {
  assert.strictEqual(
    calculateInterest('$2001.00' /*actual*/, '$0.09' /*expected*/)
  )
})

Better:

test('A loan of $2001.00 owes $0.09 interest', () => {
  assert.strictEqual(
    calculateInterest('$2001.00' /*actual*/, '$0.09' /*expected*/)
  )
})

Your unit tests also serve as documentation; make them as readable as possible for another developer who might not have the context you have right now.

Group your tests semantically

Read up on RSpec
- use describe to denote the behaviour you're testing,
- use context to group tests by common assumptions or world-states

describe('launch the rocket', () => {
  context('all ready', () => {
    test('should launch rocket')
  })
  context('not ready', () => {
    test('should do nothing')
  })
})

Your tests statements should ideally read like documentation,
- This has the added benefit of making your tests easier to review
Breaking things up in this way also avoids long test-names
- it also becomes easier to locate and debug failing tests during refactoring

Single Assert Per Test

Once your test names are discrete, have only a single assert per test
If multiple asserts are "necessary", you're probably trying to check multiple things
- the downside is that these extra things aren't documented in the test-name
- tomorrow those extra asserts might get removed because they don't look important
avoid all this drama, just keep a single assert per test.

Minimize data-sharing across tests

You might be tempted to start defining common objects and reusing them across tests, resist that urge.

It might seem like you're following DRY but it makes your tests less readable
it might also inadvertently introduce bugs into your test code
if something is really so generic that it can be included across tests, make a library out of it
- and be sure to guarantee 100% test-coverage of any library you use.

Don't assert on an Object

Take the following code as an example:

describe('createRequest', () => {
  test('set correct headers', () => {
    const actual = createRequest(
      { _csrf: 'abcd', __csrf: 'pqrst' }, // cookies
      {
        // params
        url: 'AAA',
        variables: { A: 1, B: 2 },
      }
    )
    const expected = {
      'X-CSRF': 'pqrst',
      'content-type': 'application/json',
      device: 'pwa',
    }
    assert.deepEqual(actual.headers, expected)
  })
})

"This looks fine", I hear you say, "What's the Issue?". Well, this is basically just a hidden version of having multiple asserts per test.

Here there's three asserts:
- one for the X-CSRF header,
- one for the content-type header, and
- one for the device.
To make matters worse, the test title doesn't give you any information about what the desired output is.

Refactor your tests to something like this:

describe('createRequest', () => {
  describe('headers', () => {
    test('should set X-CSRF header correctly', () => {
      const actual = createRequest(
        {_csrf: 'abcd', __csrf: 'pqrst'}, //cookies
        {
          //params
          ...
        }
      )
      const expected = 'pqrst'
      assert.equal(actual.headers['X-CSRF'], expected)
    })
    test('should set `content-type` correctly', () => {
      const actual = createRequest(
        {}, //cookies
        {
          //params
          ...
        }
      )
      const expected = 'application/json'
      assert.equal(actual.headers['content-type'], expected)
    })
    test('should set `device` header correctly', () => {
      const actual = createRequest(
        {}, //cookies
        {
          //params
          ...
        }
      )
      const expected = 'pwa'
      assert.equal(actual.headers.device, expected)
    })
  })
})

Scrutinize your Testing-Code more than your Application Code

Your tests basically contain all the information about the design of your new component
- Not only it's behaviour, but it's interface and it's dependencies
If the testing code is solid, well written, and exhaustive, refactoring Application Code will be trivial!
- If there's a gap in the tests, that's something that will only be felt in an integration test (or in Production)
This is a Process thing and is up to the team on how to enforce it

Manage your branches well

Be extra careful when resolving Merge-Conflicts in test-code
Again, the test-code can't test itself.
If a change has been made to an existing test, the fact that it passes doesn't prove anything.

Summary

Ultimately maintaining the test-suite is a matter of Discipline, Code-Guidelines and good Code-Review process as well as a reliable set of Team-mates in a trustful environment.

As individual developers I claim that if we're going to be a craftsmen about anything, we should apply ourselves to the testing code. Our future selves will thank us for it.

Good luck out there. :)

References

UncleBob Expecting Professionalism (35:05 - 41:40)
Unit Testing Smells
TDD Done Right - Tests Immutable to Refactor

Originally posted on blog.patchcording.com

Is TDD just a gimmick?

Joel Louzado — Sun, 24 Mar 2019 12:51:00 +0000

What's the big deal?

Something that has radically improved the quality and maintainability of the software I've written over the past year has been Test-Driven Development (TDD for short). My claim is that writing the test before the implementation is not just a gimmick:

Unit tests produced by TDD guarantee code-coverage in a way that tests written post-implementation cannot.

As developers I understand that there's a healthy amount of skepticism we all have so let's go through some of the common responses I get when people hear that claim.

Maybe it does, but why should I care about code-coverage?

Just to be clear, 100% code-coverage means that if a function is performing N operations, each of them are covered by a unit-test. Put another way, if someone were to delete¹ a line of code at least one unit-test should fail.

If we have coverage we can have confidence, and with that confidence you get some effects:

effort to comprehend a piece of code will always grow more slowly than the complexity of that code, because:
- there's always going to be at least one example of every potential usage, and
- you get an opportunity to play around with the code and see how it affects the test suite.
refactoring code will be much easier and faster because feedback is so much quicker
logical errors (bugs) will be much easier to spot and fix, since other people can read your tests and check if all the requirements are being fulfilled.
changes to the codebase are guaranteed to not introduce regression bugs.

So confidence (via code-coverage) is the whole game; you will see the above benefits in your codebase to the extent that the requirements are covered, simple as that.

But I could just write the function and then the tests and get the same coverage

Almost everyone I've spoken to agrees that we need unit tests because we know bugs can creep into our code. Meanwhile unit-tests are also code, don't we need to guard against bugs there?

Writing a test after the implementation leaves the possibility open that the test itself is buggy.

What do you mean by a buggy test, how can a test have a bug?

The purpose of a test is to check the correctness of the function. So anything that prevents it from doing that, is a bug. i.e. if a test isn't actually checking anything then it's not doing it's job.

Let's use the example above; let's say I finished implementing mul2, and then wrote the test below:

it('should return the product', () => {
  const actual = mul2(2, 3)
  const expected = 6
})

Notice anything? The assertion statement is missing, but the actual test will pass². Here even though everything looks okay, the test itself is not trustworthy.

What a ridiculous example, that would never happen!

Well yes it's a bit silly, but it highlights a central problem with unit testing. Namely:

How do you know that the test you've written is correct?

Any alternative proposed to TDD must be able to solve this problem or else it cannot be said to be viable.

The fact that the test is written first solves this problem. If the test is correct, it must fail.

In the example above you expect it to fail, so you'll revisit the test-code when you see it's passing even if no code is present. The rules push you to prioritize confidence in the test first before starting on the change you want to make.

What about Logical Errors, TDD won't save me there

TDD doesn't guarantee that your code is bug-free. It just guarantees that if a line is deleted that a test will fail. Therefore it's still your responsibility to write the correct tests. For example if the requirement was to multiply two numbers, but your tests are checking if the code adds the two together then your code is still wrong.

In such a scenario, TDD helps in two ways:

it makes such an error easier to spot during code-review
- since your expected value will clearly be something different than the requirement, someone can flag it as an issue
once the error is spotted, it becomes easier to rewrite the bad test or to add tests for missing edge cases.

Since refactoring is easier, this whole process happens much more quickly. And yes, while fixing one issue you're less likely to introduce a regression.

This is all horribly complicated! I'm a pretty good programmer, I don't need all this

That might be true, you might not need tests in order to produce good quality code. However, you're not the only person on your team. Also, you're probably not going to be on that team forever; tomorrow you might move on to another project or even to another company. What happens then?

Writing tests is a way to communicate³ the behaviour of the code without needing to write extensive documentation that no one will ever read (or maintain). Good-quality unit tests save an incredible amount of dev-hours, and can help a team to maintain a stable velocity as it grows.

What exactly are good-quality tests?

One key aspect of a "good" test would be that they are immutable to refactoring. That means that once a test is written, it shouldn't change as long as the requirements don't change.

Okay, but how does that translate to "saved" dev-hours?

One of hardest parts of building software is simply managing the communication overhead as the team scales. The number of connections between people is proportional to $N^2$ for $N$ members. So very quickly, it becomes almost impossible to keep everyone in sync if it requires talking to everyone about everything. Various solutions like "write documentation" or "write code that is so clear it doesn't need documentation" are all theoretically possible but are largely pipe-dreams. If it's possible to have a test suite for something, it's the ultimate safety-net and allows developers to make changes without worrying.

You say TDD is a timesaver, but updating old tests is a huge waste of time!

If you're following TDD correctly, you shouldn't find yourself updating old tests. Once you write a test, they should be immutable to refactoring i.e. it won't change as long as the API and the requirements haven't changed.

If you find yourself doing TDD but also going back over old-tests a lot, then a couple of things might be going wrong:

The Function's API needs improvement

When you're writing that first test, spend more time designing your unit's signature to be extensible. Think of the Open-Closed Principle, but applied to a function instead of a class.

We'll get into the specifics of writing that first test further down.

You're writing too much code too soon

Let's say you're trying to implement an expression: $A+!B$ (A or not-B). The first would be:

it('should return true if A is true')

What should the implementation be? Your impulse might be to write the following:

if (A) return true

However, the least code required to make this test pass would simply be:

return true

It sounds ridiculous for simple examples, but when writing complex algorithms it's common to fall into the trap of over-engineering. However, no abstraction is better than the wrong one and being disciplined about writing minimal code helps us get all the examples working before trying to solve for other concerns like performance, reusability, maintainability, etc.

In a way, TDD pushes us to focus on one thing at a time so that we can be completely focused on it. One test at a time, one solution at a time, and then refactor for one purpose at a time. When you're doing one thing, you don't have to hold everything in your mind since you know that the test suite has your back.

For a more complex example check out The Missing Practical Step in TDD

Your tests are too specific, or too restrictive

This might sound funny, but it's possible for tests to be overly specific. We've touched on this before, but tests should really be agnostic of implementation. In other words they should care about behaviour and not be asserting on structure.

The obvious example would be the test from the earlier section where we're asserting a DOM structure but there's other ways that a test can be too restrictive.

Let's say you're building a Flux-like App (using something like React-Redux), and you need some code to emit an Action. Your first test might be:

it('should fire Action-A1 when a X is true')

and your test might be:

assert.strictEqual(actual, action.of(A1))

Now, you write a new test:

it('should fire Action-A2 when X is true')

and you'll write the second test as follows:

assert.strictEqual(actual, action.of(A2))

The problem is that now you're stuck; test1 and test2 are both mutually exclusive because something can't be strictly equal to two things at the same time. In this case, saying strictEqual is overly specific; it's saying "this and only this is allowed to happen".

What might be closer to your intent is to say "whatever else is also happening, I also want this to happen". So you could rewrite your tests using some kind of contains utility as such:

assert.isTrue(actual.contains(action.of(A1)))

Now tomorrow if any number of actions are fired, your test is making sure that this action is also present. And if you've followed TDD so far, extra actions won't be fired from anywhere.

Does that mean there any cases where one shouldn't or can't use TDD?

For application development, almost everything is a good candidate for TDD. One exception is where it's not possible to write a test without being over-specific. For example there's little value in writing a test like Assert that function returns <div>Hello World!</div> and then having a function that returns <div>Hello World!</div>.

You could do it, but then tomorrow if you need to return <div>Hello <b>World!</b></div> should the test really break? I mean, I've only added an enhancement, the old test should "technically" still be valid.

The above example doesn't mean that all view-related things are automatically not eligible for TDD. To take an example of an App written in the Flux pattern, you might have a rock-solid reducer ready and waiting but then you might forget to actually fire an action from the view when a button is clicked. Packages like react-testing-library are good for use-cases like that, and can provide coverage for your views too.

Any others?

Yes, if you're writing a new package, and there's two potential APIs that would both work equally fine but they both have different (say) performance implications then that might be a bad use-case for TDD. Tests can't help you choose between two different function signatures, for example. In such a case you're really out near the edge of software-development and you're in research mode. TDD will be of more use once you've explored the space sufficiently and sorted out the architecture.

Speaking of architecture, structure your code so that more things are unit-testable, otherwise you end up with scenarios where you have to compulsively mock everything and you're testing "structure", rather than "behaviour"⁴.

I can't stress this enough though, almost everything related to Application Development can be done via TDD. As much as possible, irrespective of the structure of your application, extract your business logic into pure functions and TDD the heck out of it. You'll thank yourself later.

Your examples are a bit weird

Well we've been talking about TDD so far but it's sort of a Wittgenstein's Beetle where everyone has a thing in their box called a beetle and can only see their own box's contents. So then people might say "TDD is good" or "TDD is bad" and be talking about entirely different things.

Here's what I mean when I'm talking about TDD:

A quick recap of TDD's rules from Uncle Bob:

You are not allowed to write any production code unless it is to make a failing unit test pass.
You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are failures.
You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

Therefore,

First, write only enough of a unit test to fail.
- RED phase
Write only enough production code to make the failing unit test pass.
- GREEN phase.
Repeat till all requirements are met, refactor as needed.

In practice it might look like this. We'll take a simple example to start with. Say, I want to write a function mul2 that returns the product of two arguments:

First create the test-file: mul2.test.ts and start writing the test:

it('should return the product', () => {
  const actual = mul2()
})

As soon as this is written, the compiler will complain that mul2 doesn't exist. Only at this point do you actually create the mul2.ts file and write:

export const mul2 = () => {
  throw 'not implemented'
}

All you know is that it's a function, which is what you've declared. No implementation yet, no arguments either.

Back to the test:

it('should return the product', () => {
  const actual = mul2(2, 3)
})

The compiler will complain: "Function doesn't accept values". Fair enough, now is a good time to think about the "API" of our function:

What are the order of the arguments,
- important if the function might be curried
Can any of them be null? do any of them have default values? What are their names?
What's the return type of the function?

export const mul2 = (a: number, b: number) => {
  throw 'not implemented'
}

Since it's just a simple function, the types are pretty basic but if there were more complex behaviour, here's where we would take care of that⁵.

Back to the test, now we can add our assertion:

it('should return the product', () => {
  const actual = mul2(2, 3)
  const expected = 6
  assert.strictEqual(actual, expected)
})

The test itself is now runnable. Run it, and it'll throw "Not Implemented" as we told it to. This is the point people skip to when they think of unit-tests, but it takes a lot of thinking even to get to this point; we're just so used to doing it we forget to account for it.

export const mul2 = (a: number, b: number) => {
  return a * b
}

With that your test will pass, and you can start with the next test!

This way of writing tests seems super annoying

Writing code this way is definitely a little unnatural at first, but it makes sure that nothing extraneous ever enters your code base. When people talk about Lean-Testing, and only writing the minimum tests required, this is really what that looks like; no more tests than necessary, no more code than needed.

Over time your intuition for this style will grow and your compiler will come to feel like a helpful (if slightly pedantic) aide who just wants the best for you and your code. :)

Where would I go to learn more?

If you're looking to read more about TDD, I'd highly recommend You Don't Know TDD which was what I used when I was first learning about this. It's a really rich resource and he deals with much more complex examples than I have here.

In the meantime if you'd like to know how more about writing tests that don't break during refactoring, check out:

Your Tests Should Be Immutable

Feel free to hit me up on Twitter if you have any questions and good luck out there. 🙏

Assume the deletion was accidental, and in such a way that the code still compiles. ↩
Run it in your IDE and check for yourself if you don't believe me. ↩
One caveat, don't try to communicate the "Why" of a change using tests. Tests are about behaviour, not purpose. ↩
This is similar to the previous example, where we don't want to write a test to guarantee a particular DOM structure. Check out the tragedy of 100% code-coverage for more. ↩
If the typings are very complex, you might even want some way to develop those using TDD, but that's another topic entirely. Check out something like typings-checker if you're interested. ↩

DEV Community: Joel Louzado

Level-Up as a Developer by Working with Legacy Codebases

Functional Programming Basics

Pure vs Impure Functions in Functional Programming – What's the Difference?

Next Steps

Publish to Dev.to via RSS

Create a "Series" from Markdown Editor

A short guide on how to “make” the series widget on DEV

Dzhavat Ushev ・ Sep 27 '19 ・ 2 min read

Can Spaced-Repetition help improve your Retrospectives?

Minimum-Viable Retrospective

Spaced-Repetition is an Attention-Manager

Applying Spaced-Repetition to a Retro

Setup

First 25% of the Retrospective

Remainder of the Retrospective

Benefits

Summary

Acknowledgements

Do Stacked-PRs require re-review after merge?

Scenario

Question

Background

How would you manage spell-check of packages?

Your Unit Tests Should Be Immutable

Picture this...

Why is this a problem?

Reasons for Problem

Desired Behaviour

Achieving Test Immutability

Name your tests explicitly

Use Domain-Language while naming your tests

Use terms relevant to your users

Describe expected behaviour in the test name, rather than in the expected result

Group your tests semantically

Single Assert Per Test

Minimize data-sharing across tests

Don't assert on an Object

Scrutinize your Testing-Code more than your Application Code

Manage your branches well

Summary

Further Reading

References

Is TDD just a gimmick?

What's the big deal?

Maybe it does, but why should I care about code-coverage?

But I could just write the function and then the tests and get the same coverage

What do you mean by a buggy test, how can a test have a bug?

What a ridiculous example, that would never happen!

What about Logical Errors, TDD won't save me there

This is all horribly complicated! I'm a pretty good programmer, I don't need all this

What exactly are good-quality tests?

Okay, but how does that translate to "saved" dev-hours?

You say TDD is a timesaver, but updating old tests is a huge waste of time!

The Function's API needs improvement

You're writing too much code too soon

Your tests are too specific, or too restrictive

Does that mean there any cases where one shouldn't or can't use TDD?

Any others?

Your examples are a bit weird

This way of writing tests seems super annoying

Where would I go to learn more?

Describe expected behaviour in the test name, rather than in the `expected` result