What is this process of layering folders and then wrapping them in a namespace called?

Thu, 09 Apr 2026 02:31:07 +0800

When I recently wrote the algorithm service, as soon as I implemented modules like twap and vwap, this old problem popped up again.

If we rely on class names to enforce semantics in C++, the naming convention quickly becomes out of control. Things like TwapOrderManager, VwapOrderManager, and AlgoOrderManager sound like, “I know my structure isn’t contained, but I’ll at least add a prefix.” Frankly speaking, organizing by folders and then adding a layer of namespace isn’t about code snobbery; it’s filling the gap that C++ has because it lacks Java’s native package system.

To state the conclusion first

If I have to find a software engineering term that is the closest, I think the two words that should be mentioned are:

Modularization
Namespace management

If I want to be more precise, this type of directory organization is often doing:

Packaging by feature / Packaging by domain, which is commonly referred to as package by feature
If the business boundaries are already very strong, it will also carry a bit of bounded context.

In other words, it is not a small concept with a single standard translation name; rather, it is more like several design principles stacked together.

What is actually solved here is not just about “looking good”

When many people first see a namespace, their immediate thought is to avoid name collisions. This is certainly true; the namespace in C++ standards was originally designed to prevent naming conflicts in large projects cppreference. However, when it comes to actual business code, its value goes far beyond that.

Once the directory structure and namespace are aligned, class names no longer need to repeat the higher-level semantics.

For example, previously one might write something like this:

class TwapOrderManager;
class TwapScheduleEngine;
class VwapOrderManager;
class VwapScheduleEngine;

After adopting directories and namespaces, a more natural way to write it is usually:

namespace algo::twap {
class OrderManager;
class ScheduleEngine;
}

namespace algo::vwap {
class OrderManager;
class ScheduleEngine;
}

This removes the redundant prefix, making the semantics clearer. Because “which context it belongs to” is no longer stuffed into the class name, but rather expressed by the directory and namespace.

Therefore, this approach essentially involves extracting contextual information from the names and letting the structure carry it.

This is more like “packaging by feature”

If your directory looks like this:

strategy/
  twap/
    order_manager.h
    schedule_engine.h
    slicer.h
  vwap/
    order_manager.h
    schedule_engine.h
    slicer.h

Then you are no longer doing traditional “packaging by technical layer.”

The traditional way is more like this:

models/
services/
utils/
controllers/

This structure looks neat at the beginning, but as the business logic grows, the service directory will look like a junk heap. Classes related to one feature get scattered across different directories, making it hard to read the code because your mind keeps jumping around.

Whereas the twap or vwap approach is closer to package by feature. This means a directory first answers the question, “What is this business module about?”, and then places all the objects and processes needed for that specific business module inside it. This concept is more common in the Java world, but it works just as well in C++; the difference is that what carries it isn’t a native package, but rather a combination of “directory + namespace + header file boundaries.”

Simply put, you are organizing code by the reason for change, not by the appearance of the code.

Taking it one step further, it’s about high cohesion and low coupling

The frequently mentioned phrase in software engineering, “high cohesion, low coupling,” actually falls into this area.

Since the objects under twap collaborate frequently with each other, they should be placed closer together, and their namespaces should also be close; vwap is similar to it but not quite the same, so it deserves its own boundary. Doing this has several direct benefits:

Class names within the same module can be shorter
Dependencies between modules are easier to see
It’s easier to judge during refactoring whether changes might propagate to other areas
If you eventually need to split a certain capability into an independent library, the cost will be smaller.

This is also why many mature projects end up looking like they have consistent “directory boundaries + namespace boundaries + compilation boundaries.” In projects like QuickFIX, you can see a similar idea: types and extension points are kept under clear namespaces rather than being artificially separated by very long class prefixes QuickFIX GitHub.

When It’s Not Enough Anymore

However, don’t mythologize this either.

Simply layering folders and wrapping them in a namespace can only indicate that you are moving towards modularization; it doesn’t mean the architecture is automatically sound. Several common pitfalls are also obvious:

Directory and Namespace Mismatch

The directory is twap/, but the code contains scattered global classes, or namespace common floating everywhere. This is basically useless.

Module Boundaries are False Boundaries

There are twap and vwap on the surface, but they actually #include each other. The common logic can leak through freely, and in the end, it just moves the files around without reducing any coupling.

The longer the `common` directory, the fatter it gets

This is the most common issue. Many projects are structured quite well at first, but later find it troublesome and start dumping things into common, base, or util. By the end, instead of having truly stable abstractions that have been properly developed, they end up with a massive pitfall that everyone can touch and everyone depends on.

Structure by Layer Only, Not by Business Domain

If your directory structure is always api, service, dao, model, then many business concepts actually have no home. Class names are forced to get longer and longer, cramming everything that should be expressed by the structure back into the name itself.

So, what should it be called?

If I were communicating this within a team, I think there are three levels of description:

If you just want to speak plain language: Modularization based on directories and namespaces
If you want to sound more engineering-focused: Package organization by feature, combined with hierarchical namespaces
If these boundaries are already strongly bound to business semantics: Module division with a bounded context feel

I personally lean towards the second option. Because it is closest to the scenario you described.

What you’re doing isn’t about C++ syntax tricks, nor is it just about naming conventions; you are doing something more substantial: Using structure to carry semantics, allowing names to return to their true meaning.

When class names get shorter and file names get shorter, what you first see when reading the code is an object with clear context like twap::OrderManager, rather than something that mixes directory responsibility, naming responsibility, and implementation responsibility all together like TwapOrderManagerImpl.

Only then does the code start to feel somewhat like Java after its package structure has matured.

The Last Sentence

So, in software engineering, there are corresponding concepts, but there isn’t one single standard answer.

Broadly speaking, it’s called modularization. In terms of code organization, it’s called feature-based packaging, plus namespace management. In terms of domain boundaries, it has something to do with bounded context.

How should I put it? The most valuable aspect of this practice is never that “the names look neat,” but rather that you finally don’t have to rely on super long prefixes to compensate for structural deficiencies.

References

Writing Notes

Original Prompt

Prompt: When developing code in C++, a good practice is to organize it by folders and then wrap each class with a namespace, similar to Java’s package. This can effectively reduce redundant content in file names and class names. A classic project is QuickFIX, and we have recently used a similar design for algorithm services. Many functional modules like TWAP and VWAP are similar. Is there a specific concept in software engineering for this?

Writing Approach Summary

Start by focusing on the actual trigger points of twap and vwap in algorithm services, making the judgment clear first.
Instead of forcing the problem into a single noun, it is broken down into more accurate levels such as modularization, namespace management, and packaging by feature.
The correspondence between QuickFIX and Java packages has been retained to illustrate that C++ often needs directories and namespaces to supplement structural semantics.
The focus is on “using structure to carry semantics,” rather than remaining at a superficial explanation like “avoiding name collisions.”
Added reference links for namespace, package by feature, and bounded context to facilitate further development.

Architecture Design on Uncle Xiang's Notebook