The leftover box trap: the dangers of common structures in repositories

Do you have a box of leftovers at home? A box where you don't know exactly what's in it. It could contain anything. If you're looking for something, then definitely have a look in this box. Things get tangled up in the box easily. Things exist in the box that you've long wanted to throw away. It takes ages to find something in this box again.

Actually, you should have tidied the box long ago and then comes that one Sunday when you finally decide to tidy it up. Maybe you'll be like me. I do it every two years. Then I either throw the box away completely or put it in the cellar as it is, because tidying up is far too much effort for me, I've already bought replacements for most of the contents anyway or I prefer to buy something new instead.

From time to time, our repos also contain boxes with names such as "Common" or "Shared" - whether as a suffix, prefix or stand-alone. I also summarise folders, files and other resources with such generic labels as common structures. These terms act like instructions for use instead of a descriptive name. However, I have rarely come across common structures that really only contain "common" content. When developers don't know what to do with something, they put it in the leftover box. Since there are many different and quite justified opinions on this topic, I decided to talk to a neutral authority about it: ChatGPT.

ChatGPT:

Files and resources that are used multiple times in different parts of a project or application are placed in a commons folder. The purpose of the common folder is to avoid redundant code and promote reusability.

Sounds good at first. Files and resources that are used "multiple times" are placed in a box like this. But is something "common" if at least two people use it or if everyone uses it? If everyone is allowed to use it or only a closed group? If they actually use it or if they could just use it in general but haven't used it yet or perhaps never will?

Wouldn't it be important, especially for things that I want to use frequently and in many places, to be able to find them quickly with the help of a precise name? So I asked ChatGPT what they would expect to find in such a box.

ChatGPT:

Utility functions and classes:

• Helper functions that are used in several modules, such as formatting functions or validation functions
• Generic classes that are used multiple times, such as base classes for certain components

Constants and configuration files:

• Global constants, such as API endpoints and configuration values
• Configuration files that are used across projects

Common components and widgets:

• UI components that are reused in different parts of the application, such as buttons or form fields
• Layout components or themes that ensure a consistent presentation

Styles and assets:

• Shared CSS files or styles that are used in multiple areas
• Shared images, icons or other static resources

Utilities and libraries:

• Third-party libraries or libraries developed in-house that are required across projects
• Abstractions of external services or API clients

Tests and mock data:

• Common test helpers or mock data needed in different test cases

Thank you. But if she can describe to me so precisely what belongs in a common folder, why not just create structures with the same name and in which you can find exactly these things? I have already found other things in common folders. The things that ChatGPT expects here sound like cross-sectional solutions that I find in almost every software system. So I philosophised a bit more with ChatGPT and we came to the same conclusion, that common structures can easily be misunderstood.

ChatGPT:

Unclear limitation of content: You might think that everything that is used multiple times belongs in the commons folder, which can lead to a cluttered and unstructured folder.

• Misleading naming: The term "common" is very general and could be interpreted differently by developers.
• Lack of documentation: Without documentation, it could be unclear which files are in the common folder and how they should be used.
• Confusion about responsibilities: It could be unclear who is responsible for the maintenance and upkeep of the content in the commons folder.

ChatGPT also presented me with a solution to each problem. Firstly, the recommendation to define clear guidelines on what belongs in this box. Secondly, I should create a README file that contains the purpose and content of the folder. I should define responsibilities - i.e. appoint a maintainer or a whole team that is responsible for the common box. I also found this tip particularly interesting:

ChatGPT: Use more specific names like "shared", "utils", "components", "assets", depending on the type of files that will be stored there. This creates more clarity.

I think at this point I realised that ChatGPT and I were not going to reach a consensus on clarity. If it takes so much help to explain something, is this really the right approach? However, ChatGPT continues to adhere to common structures such as a common folder:

ChatGPT: A well-organised commons folder helps keep code clean and maintainable by avoiding redundant implementations and promoting code reusability.

On the one hand, ChatGPT discreetly hides the precondition "well organised" here. Secondly, is ChatGPT really talking about a common folder or does it really mean abstraction? Abstraction aims to derive and generalise general schemas for solving a problem. These schemas can be located in a central location, which means that they do not burden the code base, there is only one point of maintenance and, in the best case, they can be reused. This "central location" is then often a common structure. Abstraction also offers us advantages when clearly labelling files, classes and other components.

If I manage to extract a concrete observation - a schema - from a specific implementation, then this gives me the opportunity to name this schema precisely. It could be extracted and is no longer hidden in other constructs that are labelled under completely different, for example, more technically driven names. Terms such as "common", "tools" or "shared" are the opposite of precise naming.

After several unhappy long-term relationships with common structures, I was allowed to help design a frontend structure myself in 2022 and decided to avoid using "common" or "shared" in or as a label. We went through with it and it actually worked. Common structures - if "well organised" - solve the problem of central storage of abstract and cross-sectional solutions that are or can be used by a wide variety of consumers. Nevertheless, they harbour risks that can exceed the added value. In addition to creating common structures, what options do we have to achieve the aforementioned goals?

Goal: Store shared files and resources centrally

Open more and smaller boxes: Nobody said that all shared resources have to be in one folder. Instead of one large common box, professional organisers recommend many small boxes that can be stacked on top of each other, next to each other or inside each other. Each box has its own unique label. If a new item does not fit into any of the existing crates, it is time to rethink, reorganise or open a new mini crate. Of course, you can now hide these crates behind a common façade - which always means just one more click.

Goal: Regulate access rights - Common is there for everyone?

In practice, naming one folder "Common" or "Shared" and not others rarely protects against unwanted access. If you have packed everything into smaller boxes, it will be even easier to assign specific access rights. It is not the naming that indicates the possible areas of use, but documentation including models that explain structures to us and rules that kick in when we use resources outside the defined area of use. Tools that support us in this are, for example, Module Boundaries in Nx or Spring Modulith.

Common structures are the silent spaces of a screaming architecture. They rarely provide readers with further information and leave room for interpretation. This can be a good thing, but gives individual team members a lot of responsibility. They have to interpret and decide for themselves what the label means. The label on a box alone restricts the room for interpretation.

If all team members have a clear idea and common definition of what they will find in this box and what can be stored here, it can certainly work. Whether in the household or in our repos, this requires increased communication, trust and/or control. There are certainly teams that have their common structures under control and know them well. However, neither "common" nor "shared" should be a label that is tied around a hodgepodge of leftovers that don't really fit anywhere else. In this case, leftover boxes are more the result of idleness in dealing with the contents of the box, structuring it and finding suitable labels. If you put such a box of leftovers in your repo, you shouldn't be surprised if your colleagues throw things in there too. So don't set the leftover box trap for your colleagues.

Would you like to find out more about other exciting topics from the world of adesso? Then take a look at our previous blog posts.