DEV Community: Mateus Cechetto

How to Avoid Common Localization Pitfalls: Real-World Tips for Internationalizing Your Product

Mateus Cechetto — Sun, 24 Aug 2025 17:25:06 +0000

When I first joined the team building a global product, I overlooked what it truly meant to support multiple languages and cultures. Little more than a year after, and building products localized to over 10 languages, I've learned a lot about internationalization (I18n), localization (L10n), and all the things that can go wrong when you don't plan for them from day one. In this article I'll share my learning, pain points, aha moments, so you don't have to learn the hard way.

Why Should We Adapt Our Products?

We spend huge amounts of time, money, and effort building products. So when we finally launch, we want to maximize the reach of what we've built. That's where internationalization and localization come into play.

Let's quickly look at the business side of things:

TAM/SAM/SOM: If you're not familiar, these are market sizing terms:
- TAM (Total Addressable Market): Everyone who could possibly use your product.
- SAM (Serviceable Available Market): Everyone your product can currently serve.
- SOM (Serviceable Obtainable Market): The segment you're realistically targeting right now.

Without localization, your SOM is probably just a fraction of your TAM.

By localizing your product, you're instantly multiplying your potential userbase.

Key Concepts

What is I18n (Internationalization)?

Internationalization (often abbreviated as I18n) is the process of designing and preparing your software to be adapted to different languages and regions without needing engineering changes.

Think of I18n as making your product "translation-ready."

What is L10n (Localization)?

Localization (L10n) is the actual adaptation of the product for a specific locale — translating strings, formatting dates, currencies, adjusting layouts, and more.

I18n is the foundation; L10n is the finishing touch.

How do we do it at my team?

Translation Management: Crowdin
We use Crowdin to manage our translation workflow.
- Supports both free (community-driven) and paid (professional translators) options.
- Web interface to upload source files, manage translations, and download the results.
- Integrates well with GitHub and CI/CD pipelines.
- Workflow: Upload source files → Translate → Download translations
Web Frontend: React + i18next
We use i18next for our React frontend.
- Support for plurals, interpolation, and namespaces
- Integrates well with TypeScript
- Easy to use with context-aware translations
Desktop C#: System.Globalization
- We rely on System.Globalization.CultureInfo and LocalizeDictionary
- Allows setting and parsing based on locale-specific rules
- Supports dynamic updates without recompilation
CI/CD: GitHub Actions
We've automated the translation process with GitHub Actions:
- Automatically upload new source strings to Crowdin on PR merge
- Download translated files before builds
- Ensures our product is always translation-ready

Real-World Learnings

Here are some practical examples of situations where localization was tricky and some learnings I took from them:

1. Leave Space in the UI:

We had a "Subscribe" button in the UI that looked great in English, but we decided to add a small indicator showing that a sale was live. In English, "Sale" was just a 4-character word. However, when we localized the button into Portuguese, the translation for "Sale" (Promoção) was 9 characters. This led to the text overflowing and the button becoming misaligned, leaving a poor user experience.
In the mobile version of our website, one page has 4 tabs. In some languages the labels of the tabs are too long and, instead of dynamically resizing or wrapping into a new line, it pushed the layout and created a terrible vertical horizontal scroll.

General Tip: The key here is to leave space for the string to grow or shrink, but also make sure there's a fallback system for when the text is too long. You might want to set behaviors for text overflow, such as wrapping or truncating text, there is no silver bullet, the correct approach depends on the layout. This ensures your UI doesn't break under different languages, while also looking polished.

2. One Word, Multiple Meanings

Take the word "Test". In English, we use the word "test" in different contexts:
- A product feature that allows the user to run a test.
- A message that says "Test completed successfully."

However, in German, the word "Test" might get confusing because it's often used in an academic or examination context (like "Prüfung" in German). Depending on the context, the translation can vary significantly. This requires us to make sure that translators have context, so we avoid using the same word in completely different places.

General Tip: When you're using crowdsourcing for translations, always provide context to avoid confusion. This could be as simple as including a description of where the text appears or providing screenshots. Context helps translators pick the right word for the right situation, preventing misunderstandings that can result in awkward or incorrect translations.

3. Never Concatenate Strings

Imagine an error message when a user fails to complete a form. In English, the sentence is structured like this:
You forgot to enter your email.
If you try to concatenate the message in code like:
```
"You forgot to enter " + userField + "."
```
You may run into issues when translating this into languages where word order is different. For example, in German, the sentence structure might be reversed:
Du hast vergessen, deine E-Mail einzugeben.
In German, the phrase "forgot to enter" is split and the subject ("Du" meaning "You") is often placed before the verb in this context. Simply concatenating strings would lead to an unnatural or grammatically incorrect translation.

General Tip: To avoid this, use a flexible template-based system where placeholders are separated from the text and translators can adjust word order appropriately. For example:
```
"You forgot to enter {0}."
```
That, since it is just one string, can be easily translated to:
Du hast vergessen, {0} einzugeben.
Here, {0} is a placeholder for the field name, and translators can change the word order as needed for proper grammar in each language.
By using a template system, you're allowing each language's grammatical rules to be respected, without hardcoding any word order. This is key to maintaining natural, fluent translations that make sense in all supported languages.

4. Always Parse Inputs

We had a bug where we had to parse a string from our API to a float. We were calling C#'s float.TryParse() without specifying number style or culture info. That led the application to not handle correctly for user's where their machines locale were from places where the decimal separator is ',' instead of '.'.

General Tip: Always parse inputs, even if they're not directly coming from the user. For example, when your backend receives a date from the system or when pulling data from the database, ensure that the formatting is locale-aware. This avoids errors that would break the application when users from different regions interact with your product.

5. Lists, Plurals, Gendered Terms

Beware about lists, plurals and gendered terms, as languages tend to vary a lot.

General Tip: Templates should account for plurals, gendered terms, and different sentence structures. Use libraries like i18next (for frontend) or built-in features in your framework for pluralization and gender handling, and avoid hardcoding singular/plural forms.

6. Don't Delay I18n

This was a hard lesson, and the reason I wrote this. We had a feature that dynamically generated messages based on user behavior, pulling data directly from the database. The feature worked perfectly in English, but we realized too late that it was built without translation in mind. The system was generating strings with parameters that were non-translatable. By the time we realized this, it was one week before the planned product release, and we had to remove it from the initial feature set, even tho it was functionally working.

General Tip: Localization should never be an afterthought. Ideally, I18n should be integrated into the very early stages of product development. If you wait until the final stages of a release, you might end up with functional features that can't be localized, forcing you to delay the release or ship an incomplete product. Always plan for localization from day one.

Final Thoughts

If you're building a global product, localization is not optional, it's a core product concern. And like all core concerns, you should address it from day one.

You're going to make mistakes. That's okay. What matters is that you treat localization as part of the development process, not an afterthought. With the right tools, workflows, and mindset, your product can speak to the world!

I'd love to hear how your team handles internationalization and localization. What tools do you use? What hard lessons have you learned? Drop a comment below!

How Angular Schematics Help Developers Scale Architecture and Team Efficiency

Mateus Cechetto — Sat, 10 May 2025 20:45:03 +0000

As software engineers, our job isn't just writing features or fixing bugs. We're responsible for improving the processes around software and help teams move faster, safer, and more consistently. That means asking questions like:

Can we reduce repetitive tasks?
Can we encode best practices so new team members don't guess?
Can we lower the mental load of starting new features?

For Angular projects, Schematics is one of the best tools to operationalize these improvements. It lets you automate architecture, encode standards, and enforce patterns.

What is an Angular Schematic?

A schematic in Angular is a set of instructions that tells the Angular CLI how to generate or transform code. Think of it as a script that can:

Create new files using templates.
Update existing code (e.g. add a component to a module).
Enforce consistent project structure and naming.

Schematics are part of the Angular DevKit, which powers the Angular CLI under the hood.

Angular CLI's Built-in Schematics

When you run commands like:

ng generate component my-button
ng generate module user
ng generate service auth

You're using the default schematics that come with the Angular CLI. These generate standardized Angular code based on best practices and update related files (e.g. module declarations).

Custom Schematics

The built-in schematics are great out of the box, but for larger projects, they're often not enough. That's why Angular also has support for custom schematics, that let you define your own scaffolding rules and project structure.

Real-World Example #1 - Automating Test Setup

In a project, we used an in-house testing framework that wrapped Angular's TestBed with custom setup logic (mocks, utilities, providers). But Angular CLI always generated test files using default Jasmine boilerplate.

To avoid always copy-pasting the test setup, I built a schematic that created a spec.ts file with our custom setup: injecting the right testing providers, imports and assert functions.

Result: every component came with a ready to use test setup according to our project. It saved us time from rewriting the same test setup in every component, and enforced good practices, making new devs aware of our testing framework.

Real-World Example #2 - Feature Architecture

In my personal projects, I follow a feature-first architecture, breaking my app into:

features: which contain the features of the app.
shared: utility code shared across many features.
layout: header, sidebars, footer

Each feature includes:

data-access: services and state management.
feature: smart component.
ui: dumb components.

To support that structure, I created this schematic.

It does the following:

Creates a new feature folder with subfolders and base files.
Adds a service (with HttpClient injection).
Creates a smart component with routing set up.
Updates tsconfig to support path aliases (e.g., @my-feature),
Adds the new route to the central route config, intelligently placing it before the wildcard ** route.

It isn't just about saving time, it is about making good architecture easy and hard to deviate from.

Conclusion

Schematics are one of the rare tools that let you automate both boilerplate and best practices. Codegen isn't just for saving keystrokes. It's about scaling your team's ability to build the right thing the right way. Angular Schematics are a powerful, underused tool that engineers can leverage to:

Codify architecture.
Reduce onboarding time.
Lower error rates.
Improve development velocity without chaos.

If you're writing architecture docs or review checklists, consider: could this be a schematic instead?

Links - How to create a Schematic

C# Functional Programming with Delegates and Higher-order functions

Mateus Cechetto — Wed, 07 May 2025 23:45:05 +0000

C# is often known for its object-oriented roots, but it also has a very strong functional programming capability. At the heart of this functionality are delegates, which enable higher-order functions (HOFs). If you've ever used LINQ in C#, you've already used HOFs without realizing it.

What Are Higher-Order Functions?

In functional programming, a higher-order function is a function that takes one or more functions as arguments, returns a function, or both.

This concept allows for more abstract, reusable, and declarative code. In C#, HOFs are implemented using delegates, lambda expressions, and expression trees.

Delegates

A delegate in C# is a type that represents a reference to a method with a particular parameter list and return a particular type. Delegates are used to pass methods as arguments to other methods, enabling the creation of flexible and reusable code.

public delegate int MathOperation(int x, int y);

public int Add(int a, int b) => a + b;
public int Multiply(int a, int b) => a * b;

public static int PerformOperation(int a, int b, MathOperation operation)
{
    return operation(a, b);
}

public static void Main()
{
    MathOperation addOperation = Add;
    MathOperation multiplyOperation = Multiply;

    int sum = PerformOperation(5, 3, addOperation);
    int product = PerformOperation(5, 3, multiplyOperation);
    Console.WriteLine($"Sum: {sum}, Product: {product}");
}

In this example, PerformOperation is a HOF that takes MathOperation delegate as an argument, allowing different operations to be passed and executed.

In C#, there are three primary ways to define and use delegates:

Custom delegate types using the delegate keyword (like the example above)
Built-in delegates: Func<>, Action<>, and Predicate<>
Anonymous methods/Lambda expressions for inline definitions

Using built-in delegates

Func<T, TResult> is used when the delegate returns a value
Action<T> is used when the delegate returns void
Predicate<T> is used when the delegate returns a boolean. We usually use it for semantic, when we have a set of criteria and want to determine whether the parameters meet those criteria. In practice, it is the same as Func<T, bool>.

Func<int, int, int> multiply = (a, b) => a * b;
int product = multiply(4, 5);

Action<string> log = message => Console.WriteLine(message);
log("Hello from Action!");

Lambda Expressions

Lambda expressions provide a concise way to represent anonymous methods (functions without a name). They are particularly useful when working with LINQ queries and functional constructs.

var square = (int x) => x * x;
Console.WriteLine(square(5));

// using with LINQ
var numbers = new List<int> { 1, 2, 3, 4, 5, 6, 7, 8, 9 };
var evenNumbers = numbers.Where(x => x % 2 == 0);

Under the Hood of LINQ: Higher-Order Functions in Action

Language Integrated Query (LINQ) is a powerful feature in C# that allows us to query and manipulate data in a declarative manner. When you use LINQ methods like .Where(), .Select(), or .Any(), you are passing delegates into higher-order functions.

In the previous example, we used .Where(), this is what its signature looks like under the hood:

public static IEnumerable<TSource> Where<TSource>(
    this IEnumerable<TSource> source,
    Func<TSource, bool> predicate)

Func<TSource, bool> is the delegate type.
The lambda x => x % 2 == 0 matches the signature and is passed as the predicate.

Real-World example

In our case, we are building a system based on a card game. We want to make it so when a user hovers a card in hand, it highlights the cards in the deck that have synergy with the hovered card.

We added a delegate in our cardlist class, that receives a card, the decklist and returns the color that we will highlight the cards:

public Func<Hearthstone.Card, IEnumerable<Hearthstone.Card>, HighlightColor>? ShouldHighlightCard;

This gave us the flexibility to implement the function to decide if we will highlight a card in each card:

public class Thunderbringer : ICardWithHighlight
{
    public string GetCardId() => HearthDb.CardIds.Collectible.Neutral.Thunderbringer;

    public HighlightColor ShouldHighlight(Card card, IEnumerable<Card> deck) =>
        HighlightColorHelper.GetHighlightColor(card.IsElemental() && card.IsBeast(), card.IsElemental(), card.IsBeast());
}

public class Birdwatching : ICardWithHighlight
{
    public string GetCardId() => HearthDb.CardIds.Collectible.Hunter.Birdwatching;

    public HighlightColor ShouldHighlight(Card card, IEnumerable<Card> deck) =>
        HighlightColorHelper.GetHighlightColor(card.Type == "Minion");
}

In this example, the Thunderbringer card highlights cards that are both Elemental and Beast in one color, only Elemental in another, only Beast in a third color, and leaves the rest unhighlighted. The Birdwatching card highlights any card of type Minion. If you're curious, here's the implementation of the HighlightColorHelper class:

public static class HighlightColorHelper
{
    private static readonly Dictionary<int, HighlightColor> _colorMapping = new()
    {
        { 0, HighlightColor.Teal },
        { 1, HighlightColor.Orange },
        { 2, HighlightColor.Green },
    };

    public static HighlightColor GetHighlightColor(params bool[] conditions)
    {
        if (conditions.Length == 0)
            return HighlightColor.None;

        for (var i = 0; i < conditions.Length; i++)
        {
            if(!conditions[i]) continue;
            if (_colorMapping.TryGetValue(i, out var color))
            {
                return color;
            }
        }

        return HighlightColor.None;
    }
}

Conclusion

C#'s support for delegates and higher-order functions opens up a world of possibilities for developers looking to write more functional and expressive code. By embracing these concepts, you can write code that is not only more powerful but also more elegant and maintainable. Understanding these delegate forms helps you:

Read and write more expressive LINQ queries
Pass behavior around in your applications like data
Create APIs that are extensible and composable

So next time you use .Where() or .Select(), you'll know that you're already writing functional code in C#.

Why Naming Is Hard in Programming (and Why LLMs Struggle Write Real Code)

Mateus Cechetto — Sat, 03 May 2025 01:58:02 +0000

TL;DR Naming in code isn't just a syntax concern, it's a design decision. Good names reduce cognitive load, but every name is a cost. In this article, we'll look at why naming is hard, why natural language can't replace code, and when it's better to duplicate than abstract.

Naming in software is famously difficult, and for a good reason. While we tend to seek to write clean and elegant code, we often forget that names themselves are a source of complexity. Names are not just labels, they are abstractions, and each one comes with a cognitive and maintenance cost. In this post we are going to explore why naming is hard, why code duplication isn't always bad and why we should seek for simplicity.

Why Programming Languages Exist?

We didn't invent programming languages because they are cool, we created them because natural languages like English are fundamentally bad at describing technical ideas. Take the Pythagorean theorem as an example, the English version is clunky, long and not easy to understand:

the sum of the squares on the legs of a right triangle is equal to the square on the hypotenuse

The algebraic notation, a² + b² = c², is far more compact and unambiguous. That's the power of a specialized language, and the same applies to programming languages.

When we write code, we are always using (at least) 2 languages: the programming language, like Python or Java, and a natural language, usually English, for naming variables, functions and files. The programming language is precise, the natural language is not. That's where the trouble begins.

Why LLMs Can't Replace Programmers

There is a growing trend to treat large language models (LLMs) as code generators. And there are some people who fear that they can replace programmers. But here is the issue: they rely on natural language to interpret intent, and that is inherently fuzzy. Prompting in a natural language to write code is like asking a poet to draft legal policy, the precision just isn't there. Programming languages exist because English can't express what we need in software clearly. They are purpose-built for clarity and logic. English isn't. LLMs are a great tool to increase productivity, accelerate learning and produce boilerplates, but they cannot replace coding.

Every Name Is a Cost

A new name in your code, where it's a variable, function or class, isn't free, it comes with cognitive load. It has to be:

Understood by the team
Maintained
Aligned with future code changes

Even small indirections can add up:

if (shouldSendNotification(user)) {
    send(user);
}

This way you need to check what shouldSendNotification() does. Sometimes it's better to inline simple logic:

if (user.email && !user.optedOut) {
    send(user);
}

Inline logic keeps the behavior visible at the call site, which is often more readable than a name wrapping simple conditions that adds extra indirection.

In one project, I had to debug a nested flow where every condition had its own well-named function—but I still couldn't understand the logic without jumping up and down on the code. Inlining the conditions made the bug obvious in seconds.

Names Are Bad Comments

Variable and functions names are made for humans, as the compilers don't care about them. But different than comments, you cannot use punctuations, spaces, and usually want to keep names short and identifiable. That makes it hard to find good names for many things. Like comments, names can go stale. And having a bad name can mislead the developer that will face that code in the future, making it harder to maintain and potentially generating bugs. For example, instead of this:

handleUserData() {
    // actually just filters inactive users
}

Just write:

filterInactiveUsers() {

}

And if it's simple logic? Skip the name entirely:

const filteredUsers = users.filter(u => u.lastLogin < cutoff);

Have Naming Conventions

As we are seeing, naming is hard, but having consistent naming makes it easier to read and understand, reducing the cognitive load. That's why having a clear and enforced naming convention across your codebase is critical.

Think of it this way: when you see a function named getUser() in one file, and loadCustomerData() in another, and fetchPerson() elsewhere, your brain has to stop and ask:

Are these the same concept?
Do they behave the same way?
Do they return the same type of object?

This mental overhead adds up especially in large teams or mature codebases. A consistent convention eliminates that ambiguity:

getUser();
getUserById();
getAllUsers();

Here, the naming scheme is predictable. You don't have to guess whether "fetch" or "load" means something different. You can scan the code faster and understand relationships between functions more easily.

Familiar Patterns Make Code Easier to Navigate

When teams follow a naming convention (e.g., verbs for functions, nouns for models, isX for booleans), it becomes easier to guess what something does—even if you've never seen that part of the code before. For example:

isActiveUser; // boolean
calculateTotal(); // function
UserOrder; // model or class

This predictability allows you to:

Search faster
Spot mistakes quickly
Understand new code without diving into every implementation

Naming conventions are not just about syntax, they are about shared understanding. When your whole team adheres to the same patterns, you reduce misunderstandings and speed up onboarding for new engineers. They also allow tools (linters, code formatters, type checkers) to help you more effectively. The more structured your code is, the more tooling can automate quality enforcement.

Use the Real Business Language and Terms

If you're building software for a non-English-speaking domain (Brazilian finance or Japanese logistics), don't change key business terms to awkward English translations. It's better to use the language your stakeholders use, even inside the codebase. Terms like boleto, kanban, or kakeibo might not have clean English equivalents. Translating them poorly makes the code harder to understand, not easier.

I worked at a Brazilian project in the Education field where we had individual classes, group of classes defined by the platform, and group of classes defined by the user. Internally, we used Portuguese names to describe each one of them. But in code, the teams decided to use English translations, but the backend and the frontend team didn't communicate with each other, so they ended up having different names for the same things, and even worse, we had a common name meaning two different things for the backend and the frontend. So the frontend /studyPlan page was calling /api/classes and the /classes was calling/api/courses. This misalignment wasn't just annoying, it caused real bugs and friction across the teams. Using the domain's native terms in code would have avoided the confusion entirely.

Conclusion

Writing good code isn't about abstracting everything into elegant patterns. It's about being clear, honest, and readable.

Don't name what doesn't need naming
Don't abstract every repeated line
Do name things based on what they are now
Do prefer clear duplication over vague generalization
Do use business terms exactly as your users say them

Fewer names means less mental overhead, fewer misunderstandings, and cleaner maintenance.

Sometimes, the best code looks boring.

Handling Evolving Requirements: Leveraging C# Params for Variable Number of Parameters

Mateus Cechetto — Sun, 02 Mar 2025 23:00:20 +0000

When building software, we need to be aware that the requirements will change over time. Knowing that, we need to write code that is easy to maintain and to modify. Recently, in my project we had code that looked like this:


public interface ICardWithHighlight : ICard
{
    bool ShouldHighlight(Card card);
}

Pretty simple and straightforward code. The cards that implemented that interface would have to set a condition if they should highlight or not other cards. Then a new requirement arrived: cards could now be highlighted in Green or Yellow, depending on different conditions. This forced us to change the interface, because only telling if they should highlight was not enough.


public interface ICardWithHighlight : ICard
{
    HighlightColor ShouldHighlight(Card card);
}

public enum HighlightColor
{
    None,
    Green,
    Yellow,
}

public static class HighlightColorHelper
{
    public static HighlightColor GetHighlightColor(bool condition)
    {
        return condition ? HighlightColor.Green : HighlightColor.None;
    }

    public static HighlightColor GetHighlightColor(bool condition, bool secondCondition)
    {
        if(condition) return HighlightColor.Green;
        if(secondCondition) return HighlightColor.Yellow;
        return HighlightColor.None;
    }
}

Now, our code can highlight cards with one condition in green, and we use method overloading to handle two conditions as well. However, it's evident that this solution isn't the best. What if we needed to highlight with another color for a third condition, and a fourth, fifth... With the current solution, we would have to create new methods for each color, and all of those methods would look very similar.

This is where C# parameter arrays can help us. By using the params keyword, we can make our GetHighlightColor() method accept a variable number of parameters of the specified type. If you pass a multiple values, C# will automatically convert them into an array of that type.

With it, we can update the GetHighlightColor() without breaking compatibility with the existing code (when we changed ICardWithHighlight to make ShouldHighlight() return a color, we had to update our entire codebase). This approach improves flexibility and maintainability, making it easier to add new colors.

public enum HighlightColor
{
    None,
    Green,
    Yellow,
    Red,
    Blue,
    Pink,
}

public static class HighlightColorHelper
{
    private static readonly Dictionary<int, HighlightColor> _colorMapping = new()
    {
        { 0, HighlightColor.Green },
        { 1, HighlightColor.Yellow },
        { 2, HighlightColor.Red },
        { 3, HighlightColor.Blue },
        { 4, HighlightColor.Pink }
    };

    public static HighlightColor GetHighlightColor(params bool[] conditions)
    {
        if (conditions.Length == 0)
            return HighlightColor.None;

        for (var i = 0; i < conditions.Length; i++)
        {
            if(!conditions[i]) continue;
            if (_colorMapping.TryGetValue(i, out var color))
            {
                return color;
            }
        }

        return HighlightColor.None;
    }
}

How it works:

params bool[] conditions: The params keyword allows the method to accept any number of boolean conditions. The conditions are passed as an array, which gives us the flexibility to pass as many conditions as needed.
Dictionary Mapping: We use a dictionary _colorMapping to map each condition index to a specific color. This approach avoids using hard-coded indices or a long switch statement. Adding a new color simply requires adding a new entry to the dictionary.
Prioritized Matching: The method processes each condition in the order in which it is passed, returning the color for the first condition that is true. If no conditions are met, it returns HighlightColor.None.

Example Usage

// Highlights 1 cost minion
public class TrustyFishingRod : ICardWithHighlight
{
    public string GetCardId() => HearthDb.CardIds.Collectible.Hunter.TrustyFishingRod;

    public HighlightColor ShouldHighlight(Card card) =>
        HighlightColorHelper.GetHighlightColor(card is { Type: CardType.MINION, Cost: 1 });
}

// Highlights elementals in one color and beasts in other
public class Thunderbringer : ICardWithHighlight
{
    public string GetCardId() => HearthDb.CardIds.Collectible.Neutral.Thunderbringer;

    public HighlightColor ShouldHighlight(Card card) =>
        HighlightColorHelper.GetHighlightColor(card.IsElemental(), card.IsBeast());
}

// Highlights 1 cost spells in one color, 2 cost spells in other and 3 cost spells in another
public class BarakKodobane : ICardWithHighlight
{
    public string GetCardId() => HearthDb.CardIds.Collectible.Hunter.BarakKodobane;

    public HighlightColor ShouldHighlight(Card card) =>
        HighlightColorHelper.GetHighlightColor(
            card is {Type: CardType.SPELL, Cost: 1},
            card is {Type: CardType.SPELL, Cost: 2},
            card is {Type: CardType.SPELL, Cost: 3}
        );
}

In the example above, the params method allows for an arbitrary number of conditions to be passed. The caller doesn't need to worry about implementation details.

How it works:

At the call site: The params keyword allows you to pass any number of arguments of the specified type. If you pass more than one argument, they are automatically packed into an array.
At the method: The method receives an array of the specified type, and you can access the arguments as you would with any other array in C#.

Behind the Scenes:

Array Creation: When you use params, the compiler automatically creates an array to hold the passed arguments.
Performance: Because the arguments are converted to an array, the overhead is similar to any array creation in C#.
Flexibility: You can pass an array directly or provide a list of arguments, which makes it more flexible.

How Other Languages Solve the Same Problem

This problem is not new; most languages have a way to deal with it, and most solutions are very similar.

Java has varargs :

public static HighlightColor getHighlightColor(boolean... conditions) {}

How it works:

At the call site: Java allows you to pass a comma-separated list of arguments of the specified type. Java internally converts this list into an array.
At the method: The method receives the arguments as an array of the specified type.

Behind the Scenes:

Array Creation: Similar to C#, varargs in Java are converted into an array. The array is created at runtime, and each argument is added to it.
Performance: The performance is largely similar to C# in that the arguments are stored in an array, which has a fixed overhead for array creation.
Overloading: One important distinction is that Java requires you to overload methods when you want to use other arguments alongside varargs. This can introduce complexity if not handled carefully.

Typescript has rest parameters:

function getHighlightColor(...conditions: boolean[]): HighlightColor {}

How it works:

At the call site: The rest parameters syntax (...args) collects all passed arguments into a single array-like object.
At the method: Inside the method, you can treat the arguments as an array (or tuple, depending on the context).

Behind the Scenes:

Array Creation: TypeScript (and JavaScript) creates an array-like object to hold the arguments passed to the function. This is essentially a readonly array that cannot be resized after the function call.
Internally: The rest parameter syntax is a more declarative approach over the traditional arguments object, which allows for better type safety and readability.

Go has variadic functions using slices:

func getHighlightColor(conditions ...bool) int {}

How it works:

At the call site: Go functions expect a slice (which can be created from an array or passed directly as an argument). You can use the ... operator to pass an array or slice to a function.
At the method: The function accepts a slice, which is a reference to an underlying array.

Behind the Scenes:

When you call func(1, 2, 3), the compiler takes those arguments, wraps them in a slice, and passes that slice to the function. Internally, Go has to allocate memory for the slice on the heap, so be mindful of the overhead when passing large numbers of arguments.
Slice Internals: Go's slices are reference types, so when you pass a slice to a function, you are passing a reference to the underlying array (not a copy). This is more memory efficient compared to passing an array by value.
Performance: Slices in Go are much more efficient than arrays because they are dynamically sized and use a reference to the underlying array. The slice itself contains three fields: a pointer to the array, a length, and a capacity.
Flexibility: Go's slices are more flexible as they allow efficient manipulation of data without needing to recreate a new array every time.

Python has *args and **kwargs:

def get_highlight_color(*conditions):

How it works:

At the call site: Python allows you to pass a variable number of positional arguments using *args (denoted by a star *). If you want to pass keyword arguments (key-value pairs), you use **kwargs.
At the method: The method receives these arguments as a tuple (*args) and a dictionary (**kwargs), where *args holds all positional arguments and **kwargs holds all keyword arguments.

Behind the Scenes:

Argument Packing: In Python, when *args is used, the arguments are packed into a tuple. Similarly, **kwargs collects the keyword arguments into a dictionary.
Performance: The performance overhead of *args and **kwargs is relatively low compared to some other languages, as Python handles them with dynamic typing and doesn't involve the creation of strongly-typed arrays. However, there's still a small memory overhead because Python needs to create a tuple for *args and a dictionary for **kwargs to store the passed arguments.
Unpacking: Python allows you to unpack arguments passed to *args and **kwargs into other function calls, making it a flexible way to work with variable numbers of arguments.

Cherry on top of our solution

If you remember, our solution used Dictionary Mapping to get the correct HighlightColor depending on the conditions. Newer versions of C# allow us to use Pattern Matching to return the color based on the "shape" of the conditions array.

public static HighlightColor GetHighlightColor(params bool[] conditions)
{
    return conditions switch
    {
        // Matches when the first element is true
        [true, ..] => HighlightColor.Green,

        // Matches when the first element is false, second is true
        [false, true, ..] => HighlightColor.Yellow,

        // Matches when the first two elements are false, third is true
        [false, false, true, ..] => HighlightColor.Red,

        // Matches when the first three elements are false, fourth is true
        [false, false, false, true, ..] => HighlightColor.Blue,

        // Matches when the first four elements are false, fifth is true
        [false, false, false, false, true, ..] => HighlightColor.Pink,

        // Fallback for when no specific pattern matches
        _ => HighlightColor.None
    };
}

The .. in the pattern matching syntax is called the "discard" or "rest" pattern, and it is used to match and ignore any remaining elements in the array. It allows you to match a specific subset of elements in a collection while ignoring the rest. For example, [true, ..] matches when the first element is true, but it doesn't care what the rest of the elements are, allowing you to match any sequence where the first boolean is true, returning HighlightColor.Green.

The _ is a wildcard that acts as a fallback when none of the patterns are met, returning HighlightColor.None.

Conclusion

In this article, we've explored how software requirements change over time and how C# solves the problem of handling a variable number of inputs to a method. We've also looked at how other languages approach the same problem. This approach not only makes your code more flexible and scalable but also keeps it clean, maintainable, and easy to extend as your requirements evolve. Whether we're adding more conditions or introducing new colors, this solution provides a simple and powerful way to handle dynamic, condition-based logic in our application.

Understanding Method Hiding and Overriding in C#: A Real-World Problem Solved

Mateus Cechetto — Thu, 20 Feb 2025 21:15:14 +0000

I recently faced a problem at my work that revolved around populating dictionaries depending on interfaces, but one of the derived types wasn't showing up in the expected collection. After digging deeper, I came across a concept that was new to me: method hiding. It was causing my derived class to be unsuitable for the interface. I was familiar with method overriding, but I had never encountered method hiding before.

In this article, I'll walk through the problem I faced, how I solved it, and explain the concepts and differences between method hiding and method overriding.

The Problem

I was working on a system where cards were represented by classes implementing ICard interface. Cards typically implement ICard indirectly through other interfaces, such as ICardWithHighlight and ICardWithRelatedCards, which extend ICard.

public interface ICard
{
    string GetCardId();
}

public interface ICardWithHighlight : ICard
{
    HighlightColor ShouldHighlight(Card card);
}

public interface ICardWithRelatedCards : ICard
{
    bool ShouldShowForOpponent(Player opponent);
    List<Card?> GetRelatedCards(Player player);
}

The system uses reflection to dynamically load all the card classes and check which interface they implement. The goal is to populate dictionaries with card instances, keyed by their unique CardId.

The card Arcanologist has 2 different ids; therefore, it has 2 card classes: Arcanologist and ArcanologistCore, each implementing GetCardId() with its respective value. Since they refer to the same card, I used inheritance so that their ShouldHighlight() method remains consistent across both classes. However, I faced a problem: the derived class ArcanologistCore wasn't been added to the HighlightCards dictionary, even though it seemed to be a valid implementation of ICardWithHighlight.

public class RelatedCardsManager
{
    private Dictionary<string, ICardWithRelatedCards>? _relatedCards;
    private Dictionary<string, ICardWithHighlight>? _highlightCards;

    public Dictionary<string, ICardWithRelatedCards> RelatedCards => _relatedCards ??= InitializeRelatedCards();
    public Dictionary<string, ICardWithHighlight> HighlightCards  => _highlightCards ??= InitializeHighlightCards();

    private Dictionary<string, ICardWithRelatedCards> InitializeRelatedCards()
    {
        var (relatedCardsDict, highlightCardsDict ) = InitializeCards();
        _highlightCards = highlightCardsDict;
        return relatedCardsDict;
    }

    private Dictionary<string, ICardWithHighlight> InitializeHighlightCards()
    {
        var (relatedCardsDict, highlightCardsDict ) = InitializeCards();
        _relatedCards = relatedCardsDict;
        return highlightCardsDict;
    }

    private (Dictionary<string, ICardWithRelatedCards>, Dictionary<string, ICardWithHighlight>) InitializeCards()
    {
        var cards = Assembly.GetAssembly(typeof(ICard)).GetTypes()
            .Where(t => t.IsClass && !t.IsAbstract && typeof(ICard).IsAssignableFrom(t));

        var relatedCardsDict = new Dictionary<string, ICardWithRelatedCards>();
        var highlightCardsDict = new Dictionary<string, ICardWithHighlight>();

        foreach(var card in cards)
        {
            var cardInstance = Activator.CreateInstance(card) as ICard;

            if(cardInstance is ICardWithRelatedCards relatedCard)
            {
                relatedCardsDict[relatedCard.GetCardId()] = relatedCard;
            }

            if(cardInstance is ICardWithHighlight highlightCard)
            {
                highlightCardsDict[highlightCard.GetCardId()] = highlightCard;
            }
        }

        return (relatedCardsDict, highlightCardsDict);
    }
}

In the code above: - Reflection is used to load all types in the assembly that implements the ICard interface. - We check if the type implement the ICardWithHighlight or ICardWithRelatedCards to add it to the appropriate dictionary. - Lazily initialize the Dictionaries, and when one is initialized, also initializes the other one.

Now, let's take a look at the Arcanologist and ArcanologistCore classes:

public class Arcanologist : ICardWithHighlight
{
    public string GetCardId() => HearthDb.CardIds.Collectible.Mage.Arcanologist;

    public HighlightColor ShouldHighlight(Card card) =>
        HighlightColorHelper.GetHighlightColor(card.GetTag(GameTag.SECRET) > 0);
}

public class ArcanologistCore : Arcanologist
{
    public new string GetCardId() => HearthDb.CardIds.Collectible.Mage.ArcanologistCore;
}

The Issue

The problem occurred when ArcanologistCore wasn't appearing in the HighlightCards dictionary. Even though ArcanologistCore correctly implemented ICardWithHighlight and had its own GetCardId() method, it was still being ignored when populating the dictionary.

My first solution was to manually add ICardWithHighlight to the ArcanologistCore class. This worked, and the card started appearing in the dictionary.

public class ArcanologistCore : Arcanologist, ICardWithHighlight
{
    public new string GetCardId() => HearthDb.CardIds.Collectible.Mage.ArcanologistCore;
}

But I was not satisfied with this solution. I have always knew that in OOP when a class extends other, it should be implementing all its interfaces, so why did I need to explicitly write that my derived class was implementing that interface? So I start looking into an answer for this, and I found it. It is called Method Hiding.

What is Method Hiding and Method Overriding?

In C#, method hiding occurs when a derived class defines a method with the same name as a method in the base class, but without using the override keyword. This causes the derived class's method to hide the base class's method. When using method hiding, the base class method is not called — instead, the method in the derived class is used only if the reference is specifically of the derived type. This way, since GetCardId() in the base class was hidden, ArcanologistCore no longer fully implemented the ICard interface, and as a result, it did not implement ICardWithHighlight either.

Method overriding, on the other hand, happens when a derived class uses the override keyword to provide its own implementation of a method from the base class. This ensures that the method in the derived class is called, even if the reference is of the base class type.

The Solution

The solution was straightforward: instead of using the new keyword in the GetCardId() method in ArcanologistCore, I needed to use override to properly override the method from the base class. This ensures that when an object of type ArcanologistCore is referenced as an ICardWithHighlight, the overridden method is called, allowing the card to be added to the dictionary. I also had to mark the base class method as virtual to tell C# that the method can be overridden.

Here is the corrected implementation:

public class Arcanologist : ICardWithHighlight
{
    public virtual string GetCardId() => HearthDb.CardIds.Collectible.Mage.Arcanologist;

    public HighlightColor ShouldHighlight(Card card) =>
        HighlightColorHelper.GetHighlightColor(card.GetTag(GameTag.SECRET) > 0);
}

public class ArcanologistCore : Arcanologist
{
    public override string GetCardId() => HearthDb.CardIds.Collectible.Mage.ArcanologistCore;
}

Conclusion

After changing the new keyword to override in the derived class, the card was properly added to HighlightCards dictionary, and the issue was resolved. This experience helped me understand the distinction between method hiding and method overriding in C#.

Lazy Loading Pattern: When and Why to Use It

Mateus Cechetto — Wed, 22 Jan 2025 22:20:48 +0000

What is Lazy Loading?

Lazy Loading is a design pattern that defers the initialization of an object or resource until it is actually needed. Instead of creating the object at the start of the program or application, the system waits until the first time the object is accessed, at which point it is created and cached for future use. As Martin Fowler wrote:

An object that doesn't contain all of the data you need but knows how to get it.

This is particularly useful when dealing with expensive objects or resources that might not always be required. By delaying their creation until they are needed, Lazy Loading can help improve performance, save memory, and reduce unnecessary overhead.

Example: Lazy Loading in Action

Let’s take a look at an example to see how Lazy Loading works in practice.

In our case, we are building a system based on a card-based game, and one of the cards, the Mothership, has related cards that can be accessed. These related cards are minions with the Protoss tag. Here's how it could be implemented:

Computing on Every Call

public class Mothership: ICardWithRelatedCards
{
    public List<Card?> GetRelatedCards(Player player)
    {
        return HearthDb.Cards.Collectible.Values
            .Where(c => c.Entity.GetTag(GameTag.PROTOSS) > 0 && c.Type == CardType.MINION)
            .Select(c => new Card(c))
            .ToList();
    }
}

Explanation: the related cards are computed every time GetRelatedCards() is called, regardless of whether they were computed before.

Pros:

No Initial Cost: It is only calculated when the method is called.

Cons:

High Overhead: This approach incurs a high performance cost since the list is recomputed every time it is requested.
Inefficient: If the related cards don’t change often or are used repeatedly, recalculating them on every call is wasteful in terms of both CPU and memory.

Immediate Initialization

public class Mothership: ICardWithRelatedCards
{
    private List<Card?> _options = HearthDb.Cards.Collectible.Values
        .Where(c => c.Entity.GetTag(GameTag.PROTOSS) > 0 && c.Type == CardType.MINION)
        .Select(c => new Card(c))
        .ToList();

    public List<Card?> GetRelatedCards(Player player) => _options;
}

Explanation: the related cards are computed immediately when the object is created, regardless of whether they will be used.

Pros:

Simpler Code: The code is simpler because there’s no need to check for null or implement caching.
No Delay on Access: The list is always available, so there is no initial delay when accessing the related cards.

Cons:

Wasted Resources: If the related cards are not always needed (as in our case, when the card isn’t played in a game), this approach can waste memory. All related cards are precomputed and stored in memory, even if they are never used.
High Initial Cost: When an object is instantiated, the related cards are computed right away, which can slow down initialization when creating many card objects.

Initially, we used Immediate Initialization for the related cards, but the approach introduced problems when creating many card objects because of the high inital cost and memory usage.

Lazy Loading Pattern

public class Mothership: ICardWithRelatedCards
{
    private List<Card?>? _cache = null;

    public List<Card?> GetRelatedCards(Player player)
    {
        if (_cache != null) return _cache;

        _cache = HearthDb.Cards.Collectible.Values
            .Where(c => c.Entity.GetTag(GameTag.PROTOSS) > 0 && c.Type == CardType.MINION)
            .Select(c => new Card(c))
            .ToList();

        return _cache;
    }
}

Explanation:

Lazy Loading: The list of related cards (_cache) is initially set to null. Only when GetRelatedCards() is called for the first time is the list populated with the minions that have the PROTOSS tag.
Caching: After the list is created, it’s cached in the _cache field, so subsequent calls to GetRelatedCards() return the cached list without recalculating it.

Why Lazy Loading Works Best

Memory Efficiency: The related cards are only computed when necessary, and the list is cached for future calls. If the related cards aren’t used, they are never computed, saving memory.
Reduced Initialization Cost: The initial creation of the object is faster because the related cards are not precomputed upfront.
No Repeated Computation: Once the list of related cards is computed, it is cached, preventing repeated calculations and reducing CPU overhead.

Trade-offs:

The primary trade-off of Lazy Loading is the initial delay on the first access of the related cards, but this is usually a small price to pay for significant memory savings and improved performance over the long term.

Cache Invalidation

One of the key considerations when using Lazy Loading (or caching in general) is cache invalidation. While caching can significantly improve performance by reducing the need for repeated calculations or data retrieval, it also introduces the challenge of ensuring that cached data remains accurate and up-to-date.

When data changes—whether because of user actions, external data updates, or any other factors—the cached version of the data can become stale. This means that when you access the cache, you might be retrieving outdated or incorrect information. To prevent this, caches need to be invalidated or refreshed at appropriate times.

In our case, we are working with a static pool of cards. The related cards are based on predefined tags and type, and this data does not change dynamically during gameplay. The card pool is known and limited: the existent cards are fixed, and there are no external factors or events that would require frequent updates to the related cards. Because of that, cache invalidation is not a concern in our specific scenario. As a result, once the related cards are cached, they can be reused without worrying about data becoming stale.

However, if our scenario involved dynamic data (for example, if the tags or types of cards could change during gameplay, or if new cards were introduced or removed) then cache invalidation strategies would need to be implemented. To handle this, we would need to implement cache invalidation strategies, such as:

Time-based expiration: Cache is invalidated after a certain amount of time has passed.
Manual invalidation: Cache is manually cleared when the system detects that a change has occurred.
Event-based invalidation: Cache is invalidated when specific events occur.

For our hypothetical problem, event-based invalidation would be the better choice because it automatically handles changes and keeps your cache in sync without manual intervention. For example, in a game with real-time card updates, events like "card changed," "card removed," or "new card added" could trigger the invalidation of caches for related cards.

Conclusion

Lazy Loading is a powerful design pattern that can help optimize performance by deferring the creation of expensive objects until they are needed.
By comparing Lazy Loading with Immediate Initialization and Computing on Every Call, we can clearly see its benefits in scenarios where resources like memory and CPU time need to be managed carefully. When used correctly, Lazy Loading can greatly enhance the performance of your application, especially in resource-constrained environments.

Extension Methods

Mateus Cechetto — Sun, 15 Dec 2024 19:16:04 +0000

Recently on my work, I had to add a new functionality to a class that I don't control. Subclassing was my first idea, but it didn't feel good because it had tightly coupled to the existing class and had limited flexibility. After looking for alternatives, I considered composition but then I discovered C# Extension Methods.

Extension Methods let you "attach" methods to existing classes or objects. This approach:

Enhances readability by using object-oriented syntax. It allows the developers to call the added functionality as if it were part of the original class
Avoids code duplication
Maintains separation of concerns, keeping extensions separate from the original class, which aligns with the Open/Closed Principle of object-oriented design—software entities should be open to extension but closed for modification
Reduces boilerplate
Enables the creation of fluent interfaces, which allow for chaining method calls in a way that mimics natural language

For example:

word.IsUpperCase();

This simple, fluent syntax is far more intuitive than using standalone utility functions.

How Different Languages Implement Extension-Like Features

C# and Kotlin: Native Extension Methods

Both C# and Kotlin provide first-class support for extension methods or functions. These mechanisms are type-safe and validated at compile time.

C#: Extension Methods: C# defines extension methods as static methods in a separate class, using this to indicate the type being extended:

  public static class StringExtensions
  {
      public static bool IsUpperCase(this string str)
      {
          return str.All(char.IsUpper);
      }
  }

  // Usage
  string word = "HELLO";
  bool result = word.IsUpperCase(); // True

Kotlin: Extension Functions Kotlin’s implementation is concise and integrated seamlessly:

  fun String.isUpperCase(): Boolean {
      return this == this.uppercase()
  }

  // Usage
  val word = "HELLO"
  println(word.isUpperCase()) // True

JavaScript: Prototype Extension

JavaScript allows extensions through its prototype mechanism, enabling developers to add methods to built-in objects.

String.prototype.isUpperCase = function () {
    return this === this.toUpperCase();
};

// Usage
const word = "HELLO";
console.log(word.isUpperCase()); // True

While powerful, modifying prototypes is not recommended and comes with risks:

Pollution: Adding methods to native prototypes can conflict with future JavaScript features or third-party libraries.
Global Effects: Changes apply globally, affecting all instances of the type.
Debugging Challenges: Modifying core types makes issues harder to track.

Utility Functions in Java and TypeScript

Languages without native support, like Java and TypeScript, rely on utility functions.

Java

  public class StringUtils {
      public static boolean isUpperCase(String str) {
          return str.equals(str.toUpperCase());
      }
  }

  // Usage
  String word = "HELLO";
  boolean result = StringUtils.isUpperCase(word); // True

Typescript

  function isUpperCase(str: string): boolean {
    return str === str.toUpperCase();
  }

  // Usage
  const word = "HELLO";
  console.log(isUpperCase(word)); // True

Utility functions are safe but lack the fluency of object-oriented extension methods.

Dynamic Languages and Monkey Patching

Dynamic languages like Python and Ruby allow direct modification of existing classes or objects, a technique known as monkey patching.

Python

  def is_upper_case(self):
      return self == self.upper()

  str.is_upper_case = is_upper_case

  # Usage
  word = "HELLO"
  print(word.is_upper_case())  # True

Ruby

  class String
      def is_upper_case
          self == self.upcase
      end
  end

  # Usage
  word = "HELLO"
  puts word.is_upper_case # True

While monkey patching is flexible, it’s risky for similar reasons as js prototype.

Rust: Traits

Rust offers a unique alternative with traits and trait implementations. Instead of modifying a type directly, you implement a trait to add functionality.

trait IsUpperCase {
    fn is_upper_case(&self) -> bool;
}

impl IsUpperCase for String {
    fn is_upper_case(&self) -> bool {
        self == &self.to_uppercase()
    }
}

// Usage
let word = String::from("HELLO");
println!("{}", word.is_upper_case()); // True

Rust’s traits ensure extensions are scoped and composable, offering safety without sacrificing flexibility.

Real-World example

One very useful case in C# is to filter out null values from IEnumerable<T>? transforming it into IEnumerable<T>:

public static class EnumerableExtensions
    {
        public static IEnumerable<T> WhereNotNull<T>(this IEnumerable<T?> source) => source.Where(x => x != null).Cast<T>();
    }

Comparison Table

Language	Extension Mechanism	Pros	Cons
C#	Extension Methods	Type-safe, elegant syntax	Requires static class
Kotlin	Extension Functions	Concise, seamless integration	Limited to scoped extensions
JavaScript	Prototype Extension	Powerful, dynamic	Risk of conflicts, global effects
Java, Typescript	Utility Functions	Safe, avoids modifying types	Verbose, lacks fluency
Python, Ruby	Monkey Patching	Flexible, easy to implement	Debugging challenges, risky
Rust	Traits	Type-safe, scoped, composable	Slightly verbose

Balancing Power and Safety

Extension methods offer a clean and flexible way to enhance existing types without modifying their source code, improving readability and maintainability.
Each language’s approach to extending functionality reflects its core philosophy:

Dynamic languages prioritize flexibility but risk stability.
Statically typed languages favor safety and maintainability.
Rust’s traits stand out as a hybrid, balancing flexibility with compile-time guarantees.

Allowlist vs Denylist: When to use them

Mateus Cechetto — Sun, 03 Nov 2024 00:27:43 +0000

In software development, managing access to resources and features is a common challenge. Two common approaches to regulate access are the use of allow and deny lists. These strategies determine whether certain users, inputs, or systems are allowed or denied access, but they do so in opposite ways.

It's worth noting the recent shift in terminology within the software industry. Terms like 'allowlist' and 'denylist' are being adopted over the older 'whitelist' and 'blacklist' to promote more inclusive language. This shift reflects a broader industry trend toward fostering diversity and inclusivity in both coding practices and team dynamics.

What is Allowlist?

An allowlist is a list of entities (such as users, inputs, or services) that are explicitly permitted to access a feature or resource. If something is not on the allowlist, it is automatically denied access by default. They are often used to control access to:

Feature Flags: Granting early access to new features for specific users or testers.
APIs: Allowing only approved applications or users to interact with your API.
Inputs: Ensuring only approved inputs or data formats are accepted by the system.

Advantages of Allowlisting

Tighter Control: Allowlisting provides a high level of security, allowing only pre-approved entities to access the system. This is ideal when the number of trusted users or inputs is limited and well-defined.
Improved Quality Assurance: When deploying a feature to a select group of users (such as beta testers), a allowlist ensures that only trusted individuals access it, minimizing unexpected issues.
Better Prevention of Abuse: Allowlists can prevent unauthorized or malicious access by ensuring only verified entities are granted permission.

Disadvantages of Allowlisting

High Maintenance: Managing an allowlist can be time-consuming, especially as the number of approved users, inputs, or services grows. Every new entity must be vetted and added manually.
Limited Flexibility: Legitimate users or inputs can be inadvertently excluded if not added to the list, which can cause delays or inconvenience during development.
Slower Iteration: For fast-moving projects, constantly updating the allowlist can slow down progress, especially when dealing with external partners or APIs that require regular changes.

What is Denylist?

A denylist is a list of entities that are specifically denied access, while everything else is permitted by default. In software development, denylisting is commonly used to:

Block Unwanted Users: Preventing bad actors or known spammers from accessing an app or platform.
Filter Out Bad Inputs: Rejecting harmful data, such as SQL injection attacks or cross-site scripting attempts.
Control Feature Access: Disabling features for specific users who may have violated terms of service or encountered a known issue.

Advantages of Denylisting

Less Restrictive: Denylists allow for more flexibility, as they only block specific entities, letting new users or inputs flow through without needing explicit permission.
Easier to Implement: In fast-paced development environments, denylists are easier to manage because they require action only when there is something to block, rather than vetting each new user or input in advance.
Broader Access: Denylists are well-suited to systems with a wide range of users or inputs, where most entities are safe or acceptable, and only specific ones need to be blocked.

Disadvantages of Denylisting

Security Gaps: Denylists rely on identifying known issues or bad actors. If an attacker or harmful input isn't already on the list, it could slip through undetected.
Reactive Approach: Denylists tend to be reactive rather than proactive, as they focus on blocking known threats. New or evolving issues may go unnoticed until damage is done.

When to use Allowlists vs Denylists

Allowlists: Use when you need tight control over access, such as rolling out features or managing critical resources.
Denylists: Use when you have a broad user base or only need to block known threats and exceptions.

Criteria	Allowlist	Denylist
Default Behavior	Denies all by default; only approved entities are allowed	Allows all by default; only blocks specific entities
Best Use Case	Restricted access systems, e.g., admin panels	Public-facing systems, e.g., user-generated content
Security Approach	Proactive; limits risk by approving only known entities	Reactive; blocks known malicious entities after they act
Maintenance	High; requires ongoing approval for new users/entities	Lower; only requires updating to block malicious activity
Potential Pitfalls	Risk of excluding legitimate entities accidentally	Risk of letting unknown malicious entities slip through

Real-world examples

The inspiration for discussing this topic came from two scenarios my team faced last month, where we had to choose between using an allowlist or a denylist.

Game Modes Tracking: In this situation, we needed to track specific features for different game modes. Each feature was tied to an allowlist of game modes where it made sense to exist. This way, if a new game mode was introduced, it wouldn’t automatically receive those features, preventing any potential information leaks.
Card Draw Source Tracking: The second scenario involved tracking whether a card was drawn generically or via a tutored draw (where specific cards are targeted). For tutored draws, revealing the source of the draw is crucial, while showing the source of a generic draw adds noise. We opted for a denylist in this case. If we missed identifying a card, it would result in showing unnecessary information (just noise, but not critical). With an allowlist, missing a tutored card would result in missing valuable information, which would have been much worse.

Conclusion

Choosing between allowlists and denylists depends on the specific requirements. If you need strict control and limited access, an allowlist offers higher security. For larger, more dynamic systems where the majority of users or inputs are safe, a denylist offers more flexibility. Both approaches have their pros and cons, but understanding when and how to apply them will help you manage access effectively in your software projects.

Complicate Your Personal Projects

Mateus Cechetto — Fri, 04 Oct 2024 00:56:24 +0000

Recently, personal projects have increasingly become a gold rush where people are focused on building the simplest "microsaas" possible in the hope of creating passive income. There's nothing wrong with profitable projects or launching a Minimum Viable Product (MVP) and iterating. In fact, that’s how most successful products are built, and its a practice I do myself. But in this article, I want to offer a different perspective: why you should deliberately complicate your personal projects as much as possible.

The Fun Factor

When I start a personal project, I usually have two goals: solve a problem I face in real life and improve my skills. This is why I often choose technologies I’m still learning or apply patterns I’m not fully comfortable with yet. It challenges me to deepen my understanding of these technologies, and since it’s a personal project, I have the freedom to make mistakes and learn from them. The freedom to try new things without constraints is what makes personal projects fun. The fun itself is the motivation that keeps the personal project from being abandoned like so many unfinished ideas that every engineer has.

In my professional life, I follow established patterns and maintain consistency within the codebase. In contrast, personal projects give me space to experiment. I try different approaches, play with patterns I’m unfamiliar with, and if I find them valuable, I start applying them in my professional work as well. This experimentation alongside the autonomy of making and learning from my own mistakes, makes the process more enjoyable.

Example 1: Custom Hearthstone Deck Validator

Take one of my recent personal projects, a custom Hearthstone deck validator. The project’s purpose was to allow users to define custom deck-building rules for tournaments or casual play. Instead of taking the easy route and creating dropdowns for predefined options, I complicated things on purpose. I opted for a text input where users could write the rules they wanted, which meant I had to create a Domain-Specific Language (DSL) to process and validate these rules.

To build the DSL, I revisited concepts I hadn’t touched since my compilers classes, such as tokenization. Rather than using regular expressions, I manually tokenized the input to have more control and flexibility. Manual tokenization allowed me to separate syntax and semantic validation, making error messages more helpful and detailed. This project was also the first time that using Test-Driven Development (TDD) genuinely enhanced my development experience.

On top of that, I learned about Monaco Editor (the same editor that powers Visual Studio Code) and decided to integrate it to provide real-time syntax highlighting for my DSL. I had to learn how to add a custom language to it, and it was incredibly satisfying when the editor correctly highlighted valid input and flagged errors. Each new piece of complexity taught me something new, things I would not have learned if I had taken the "easy" route.

Custom Hearthstone Deck Validator

Example 2: Hearthstone Set Review Hub

Another personal project that became more complex than necessary was the Hearthstone Set Review Hub. The core idea was simple: a central platform where players could rate new cards. That's something a basic spreadsheet could handle. But I decided to spice it up. I wanted to make it interactive for streamers by allowing their Twitch chat to submit ratings in real time directly to the hub.

This led me to learn about IRC protocol and discover tmi.js. The complexity escalated when I realized that I had to handle multiple streamers using the system at the same time, requiring creating and managing multiple instances of TMI clients.

Then, as the next Hearthstone expansion approached, I found myself on a tight deadline. I needed to release a working version before the expansion hype peaked (in approximately 20 days), which forced me to simplify my product. To make the most minimal viable product, I built a simple UI with just text fields and a button. Instead of using a database, I opted for Google Sheets to store the data, as streamers were already familiar with spreadsheets. My system would simply add a new page with chat ratings to their existing spreadsheet. I had to learn the Google Sheets API and handle its rate limits. To avoid exceeding the rate limit, I batched the ratings before writing them. But this introduced a new problem: how should the system handle multiple ratings for the same card? If a user sent more than one rating, how would I update the previous one if it was in a different batch?

I solved this by storing all ratings in memory until the streamer finished rating the card. Only then would I send the data to the spreadsheet. These decisions, even though they seem obvious in hindsight, were challenging under time pressure. Each problem I faced required a new skill or a new way of thinking. As my operating systems professor once said:

"My exams are easy. It’s simple to spot a deadlock or a race condition when you've spent the past months studying them and you're analyzing a piece of code that probably contains one. The real challenge is recognizing these issues when your production system is behaving unpredictably, and you're not even sure they could be the cause."

I released the project, and it was well-received by the community, leading to donations, contributor interest, and further development.

HS Set Review Bot MVP

As development continued, I didn't stop challenging myself. This project significantly enhanced my skills in writing scripts to automate various tasks. It also deepened my understanding of observability, caching strategies, analytics, CI/CD, web scraping, and even Machine Learning. With the help of an old classmate, we trained a classification model to rate card after the expansion, using cards stats data to compare with the ratings users gave before the expansion.

Current HS Set Review Homepage

Current HS Set Review Review Page

Why Complicate Things?

Both of these projects became much more complex than they needed to be. But this complexity forced me to learn at an accelerated pace. The things I learned in just a few months compares to what I could have gained over years in a typical work environment. The key difference was that I was the one making the decisions, dealing with the consequences, and reaping the rewards when things went well.

At work, you typically have well-defined roles and responsibilities, and a lot of decisions are made by senior team members. You might specialize in one part of the stack, rarely touching others. But in a personal project, you're the architect, developer, tester, and product manager all in one. You control the technology choices, the design, and how deep you want to dive into different areas of the stack. This forces you to broaden your skills and become a more well-rounded developer.

Knowledge > Money

While these projects never had the goal of making money, the knowledge and experience I gained were far more valuable in the long run. They directly contributed to my career growth. I landed my current position because one of those projects caught the attention of a company. Additionally, these projects give me plenty to talk about in interviews and meetups. People get excited when I share the lessons learned, the decisions I made, and the struggles I faced.

Your career, like life, is a marathon, not a sprint. Focus on becoming valuable, and the rewards will follow, rather than fixating on getting money as quickly as possible.

So, my advice: complicate your personal projects. Choose technologies you’re unfamiliar with. Push yourself into areas you haven’t explored before. Learn from your mistakes. You’ll walk away with a wealth of knowledge, confidence, and skills that will benefit you far more than trying to build the simplest microsaas for quick cash.

When does TDD make sense?

Mateus Cechetto — Sun, 22 Sep 2024 19:01:23 +0000

Throughout my career, I often heard that Test-Driven Development (TDD) is an effective approach for building software. However, I struggled to see the benefits for a long time. This changed recently when I was working on a project where TDD was an ideal fit. In that instance, it significantly improved my development process, making it faster and less prone to errors. In this article, I will explain when to use TDD and why it works best in certain scenarios.

When TDD Falls Short

While TDD is a powerful methodology, it's not always the right tool for the job. Here are a couple of scenarios where applying TDD can be more problematic than beneficial:

Unclear or Evolving Requirements: When requirements are ambiguous or still evolving, writing tests upfront can feel like shooting in the dark. In these cases, we need to explore the problem space, experiment with different approaches, and iterate on the design as we learn more. Trying to lock in tests before understanding what the code should do wastes time and stifles creativity.
Low Domain Logic: In cases where the codebase is mostly concerned with handling input/output (I/O) operations or simple tasks, there’s little value in writing tests first. For example, building a "Hello World" program is a clear case where TDD is overkill. The code is too simple, too stable, and has little to no logic to test. If the code heavily interacts with external systems like databases, file systems, or APIs, writing unit tests upfront can be inconvenient and less effective. The high ratio of boundary code (e.g., I/O) versus actual domain logic means that the return on investment for TDD is low.

When to use TDD

Now let’s look at when TDD shines. From my recent experience, I found that TDD works best in scenarios where:

Clear Requirements: In the project I mentioned, the requirements were crystal clear. I knew exactly what the expected output of each function should be for every type of input. This allowed me to write the tests first with confidence that they reflected the desired behavior. Because of the clarity, the tests guided the development, ensuring that my implementation was correct and met the business needs from the get-go.
Complex Domain Logic: If you’re working on a system with a lot of complex business rules, TDD becomes incredibly valuable. In this case, each test verifies that a specific part of the logic behaves correctly. I experienced this firsthand: after adding each new piece of functionality, I ran my tests to see what was missing and iterated on the code until all tests passed. This made me confident that each new change didn’t break any existing behavior.

Why to use TDD

Behavior-Driven Focus: Writing tests first helped me focus on the behavior, not the implementation. This is an essential distinction, as it prevents tests from being too tightly coupled to the internal workings of the code. Instead, the tests reflect what the code should do, making refactoring easier without breaking the tests unnecessarily.
Long-Term Maintenance: One of the biggest advantages of TDD is the long-term stability it brings. As I revisited the project later to add new features or improve existing functionality, my existing tests acted as a safety net. I could confidently make changes without fearing regressions because the tests ensured everything still worked as intended.

Pratical Example: Building a Custom Deck Validation DSL with TDD

In one of my recent projects, I applied TDD to build a custom Hearthstone deck validation Domain Specific Language (DSL). The goal was to create a system that allows users to define complex deck-building rules in a human-readable format. First, I designed how the language would look like, and what scenarios it should cover. This clarity in requirements, coupled with the system's complex logic, made it an ideal use case for TDD.

The project had two core components that benefited greatly from a TDD approach:

RuleValidator: This component is responsible for validating a user’s input to ensure it follows the DSL’s syntax and semantics. It tokenizes the input, checks for errors in structure, and returns a list of validation errors with clear messages for the user. If the list is empty, it means the input is valid. The TDD approach ensured that all possible validation scenarios, including edge cases, were tested during implementation.
- Tests
- Implementation
RuleGenerator: Once an input is validated, the RuleGenerator transforms it into TypeScript code that defines the deck-building rules. It first invokes the RuleValidator to confirm that the input is correct. For valid input, it generates a function representing the rule, based on attributes, operators, modifiers, and values. This generated code is then used by the DeckValidator to verify whether the cards in the deck follow the defined rules.
- Tests
- Implementation

By writing tests first, I ensured that all scenarios designed for the DSL were covered, which guided the development process from start to finish. The tests acted as a checklist, helping me verify that each feature was implemented correctly and completely. This process also made development smoother—rather than relying on memory to track what still needed to be done, I simply ran the test suite and worked through any failing tests.

The benefits of TDD became even more apparent when I refactored the code. For instance, I broke down larger functions into smaller, reusable ones, improving the overall design. Additionally, when I decided to add new modifiers (> and < for comparing values), I was confident that the existing functionality would remain intact because the tests served as a safety net, catching potential regressions.

Conclusion

TDD is a valuable methodology when used in the right context. It excels when you have clear requirements, a high level of domain logic, and need a reliable way to prevent regressions over time. However, it can slow you down in exploratory phases or for trivial, boundary-heavy code. Knowing when to apply TDD and when to hold off is the key to getting the most out of it.

How to Test Functions That Return Functions in TypeScript with Jest

Mateus Cechetto — Sun, 15 Sep 2024 23:03:16 +0000

In one of my recent projects, I had a function that, given an input, generates and returns a new function. While this is not an everyday occurrence, it's crucial to understand how to test such patterns effectively. In this article, we'll explore techniques for testing functions that return functions in TypeScript using Jest.

The Challenge of Function Equality

Initially, I approached testing by comparing the generated function to an expected function:

describe("function generator", () => {
    const generator = (message: string) => {
        return (name: string) => {
            return `${message}, ${name}`;
        };
    };

    it("shoud return the expected function", () => {
        const expected = (name: string) => {
            return `hello, ${name}`;
        };
        expect(generator("hello")).toEqual(expected);
    });
});

This test fails:

    expect(received).toEqual(expected) // deep equality

    Expected: [Function expected]
    Received: [Function anonymous]

The failure occurs because JavaScript functions are objects with unique identities. Even if two functions are structurally identical, they are not considered equal unless they reference the same object. Moreover, generated functions often create closures, capturing variables from their surrounding scope. These closed-over variables, or "lexical environments" add another layer of complexity to testing.

First-Class Functions and Closures

Before we dive deeper, let's review some core concepts. In JavaScript (and by extension, TypeScript), functions are considered first-class objects, meaning they can:

Be stored in variables or properties
Be passed as arguments to other functions
Be returned as the result of another function

This allows for powerful patterns like higher-order functions (functions that return other functions). When a function is generated inside another function, it often forms a closure, meaning the inner function has access to variables defined in its parent scope, even after the parent function has finished executing.

For instance, in the following code:

const generator = (message: string) => {
    return (name: string) => `${message}, ${name}`;
};

const greet = generator("hello");
console.log(greet("world")); // "hello, world"

The function greet closes over the message variable, keeping it alive even after generator has returned.

Different Testing Strategy

To effectively test functions that return other functions, we must focus on the output of the generated function rather than comparing the functions themselves. This approach ensures we're validating behavior, which is the true goal of testing.

When testing a sum function, for instance, you check if the result is as expected: expect(sum(1, 2)).toBe(3). Similarly, when testing a generator function, we must evaluate the returned function's behavior by calling it with various inputs.

Here's how to properly test a function generator:

describe("function generator", () => {
    const generator = (message: string) => {
        return (name: string) => {
            return `${message}, ${name}`;
        };
    };

    it("should handle different messages and names", () => {
        const resulting = generator("hello");
        expect(resulting("world")).toEqual("hello, world");
        expect(resulting("Mateus")).toEqual("hello, Mateus");

        const resulting2 = generator("bye");
        expect(resulting2("world")).toEqual("bye, world");
        expect(resulting2("Mateus")).toEqual("bye, Mateus");
    });
});

By testing the output, we can ensure that the generator function works correctly for different inputs, providing the desired behavior.

Testing More Advanced Scenarios: Closures

Now, let's dive into some more advanced scenarios. When testing generator functions that form closures, you may want to validate that the closed-over variables are handled properly, and that the function behaves as expected even in edge cases.

Consider this function:

const counterGenerator = (start: number) => {
    let counter = start;
    return () => ++counter;
};

Here, the generated function closes over the counter variable. Testing this pattern ensures that each invocation of the returned function correctly updates the counter:

describe("counter generator", () => {
    it("should increment the counter on each call", () => {
        const counter = counterGenerator(10);

        expect(counter()).toBe(11); // First call, counter is incremented to 11
        expect(counter()).toBe(12); // Second call, counter is incremented to 12
        expect(counter()).toBe(13); // Third call, counter is incremented to 13
    });
});

In this case, you're not just testing the output of a single call but also ensuring that the closure works properly by keeping the internal counter variable alive and updating it between function calls.

Conclusion

Testing functions that return functions in TypeScript can seem tricky at first due to the nature of JavaScript's function objects and closures. However, by focusing on testing the behavior of the generated functions—rather than comparing them directly—you can effectively validate their correctness.

To recap:

Functions in JavaScript are first-class objects with unique identities, which complicates direct comparison.
The solution is to test the output of generated functions by calling them with different inputs.
For more complex cases, like closures, ensure that your tests validate how closed-over variables are handled over time.

By following these strategies, you'll be well-equipped to test function generators effectively in your projects.