Two Meanings, One Word

The word "ascending" has two different meanings in software, and conflating them causes problems.

In business terms, "ascending" often means "what we want to see first"—the best values, the top performers, the most important items.

But in technical database terms, "ascending" has a precise definition: ordering from lowest to highest value, where the smallest number comes first. For metrics like revenue or clicks, these align: we want high values first, so we sort descending.

But for metrics like rank position or response time, they conflict: we want low values (rank 1, fast times) first, which means sorting ascending. Using the same word for both concepts creates a dangerous ambiguity that's easy to miss and hard to debug.

I hear some of you thinking "types solve it", but even if we use the same terms across layers, they are distinct concepts that need clear differentiation in order to make source code easy to read, which is the highest value source code can have (even in times of AI).

Contents

1. Naming and Software Engineering
2. The Problem
3. A Software Engineering Problem?
4. The Solution: Distinct Vocabularies
5. Why Introducing a New Names Makes Sense
6. Conclusion
7. My ADR for this

Naming and Software Engineering

Every developer faces the tension between clarity and explicitness. We want code that reads naturally, but we also need precision to prevent bugs. Sometimes, the familiar term is actually the dangerous one. I recently encountered this with sorting logic in an application I am working on. The standard terms "ascending" and "descending" seemed like the obvious choice, until I realized they meant fundamentally different things at different layers of the stack.

The Problem

We have metrics where "best" means different things numerically:

• Clicks: Higher is better (1000 clicks beats 100 clicks)
• Position: Lower is better (position 1 beats position 10)

In the frontend, I had a parameter ascending=true that meant "show the best values first." But here's the issue:

For clicks:

• Frontend: ascending=true → show highest first
• Database: ORDER BY clicks DESC

For position:

• Frontend: ascending=true → show lowest first
• Database: ORDER BY position ASC

The same frontend parameter was mapping to opposite database operations depending on which column the user was sorting by.

A Software Engineering Problem?

I think so.
This isn't about finding a bug. It is about preventing bugs through better design, precise terminology, readable source code and code that speaks an unambiguous language.

It might cause:

• Semantic collision - The word "ascending" has a precise database meaning (low to high) but a context-dependent business meaning (best to worst, which varies by metric)
• Hidden complexity - The translation logic between "ascending" in the frontend and ASC/DESC in the database is implicit, requiring developers to remember which metrics are "lower is better"
• Maintenance burden - Every new sortable column requires carefully thinking through the mapping, increasing cognitive load during code reviews
• Blurring boundaries - The technical layer (the database) and the business layer (the frontend) might blur and reading code becomes harder, especially for new team members

The Solution: Distinct Vocabularies

I'm implementing a change that uses different terms at each layer:

• Frontend: sort_direction=best_first
• Database: ORDER BY ... ASC/DESC

Example:

GET /api/data?metric=clicks&sort_direction=best_first
GET /api/data?metric=position&sort_direction=best_first

The key insight: by using different words (sort_direction instead of order, best_first instead of ascending), we make the need for translation obvious and explicit.

The word "order" and "ascending" have a determined meaning in databases, so using them in the frontend for a different meaning is a recipe for confusion.

Why Introducing a New Names Makes Sense

Yes, sort_direction is more verbose than order. Yes, best_first is less familiar than ascending. But this is intentional. The unfamiliarity forces awareness. Which is not a good enough reason in itself, but "sort" and "order" are just different words and once you see this and understand where the boundaries are, you get used to it quickly. When you see sort_direction or best_first in code, you immediately know:

• This is user-facing vocabulary expressing intent
• It requires translation to database terms

Compare this to seeing ascending=true, it is so familiar that you might not realize it needs interpretation at all. Different layers, different languages.

The frontend speaks in user intent ("show me the best"), the database speaks in technical operations ("sort numerically ascending").

Self-documenting architecture. The vocabulary itself signals that there's a translation layer. New developers can't accidentally bypass the mapping because the terms don't match up.

Conclusion

In software engineering, clarity trumps brevity. Using the same words for different concepts creates ambiguity that leads to bugs and maintenance headaches. By adopting distinct vocabularies for user intent and technical operations, we can make our code more readable, maintainable, and less error-prone.

Just making up words that are even harder to understand would definitely be a trade-off that is not worth it. So watch the traps of familiar terms and choose your words wisely.

I think it is worth here. What do you think?

My ADR for this

In case you use ADRs (Architecture Decision Records) in your projects, here is mine for this decision. I even shorted the parameter called sort-direction to just be best-last and being a boolean, but the idea stays the same and the naming is just better, in my opinion.

# <number>. "sort"+"best-last" in frontend, "order"+"desc" in backend

## Status

Accepted

## Context

All context is described in https://picostitch.com/blog/2025/12/asc-and-desc-confusing/.
In short: Frontend "ascending" means "best first", which can be either ASC or DESC in SQL depending on the metric.

## Decision

In the frontend we use "sort" + "best-last", in the backend "order" + "asc/desc".

To distiginish vocabularies between frontend and backend to avoid confusion,
the frontend, which is the sort and pagination parameter in the URL and in the frontend-related code (such as views)
uses "sort" and "best-last".
- "Sort" is NOT "order", so it's easy to distiguish the two layers.
- "best-last" is a bool, which is by default false and doesn't need to be given in the URL
- "order", "order-by", etc are only used when we talk about the database layer, so the sort param is mapped and translated there.
- "asc" and "desc" are only used in the database layer, they have a very defined meaning there.

## Consequences

- pro: Prevents bugs due to semantic collision
- pro: Clearer code, less confusion
- pro: Explicit mapping between frontend and backend vocabularies
- pro: Less cognitive load when reading code or reviewing changes
- pro: Easier onboarding for new developers
- con: Distinct vocabulary to learn