🐍🛢️ Technical Snake Oil - how hastiness impedes your future self

Release date: 2025-04-07

Technical snake oil is my term for technology, code, commands, configs or anything else of which the applying person doesn't fully understand what it does or how it works.
It leans on the already established "snake oil" idiom, which describes "a substance that is sold as a medicine but that is not at all effective and may be harmful".
And after writing this I think this applies to everything we do and not only technical stuff.

I'll be referring to an ominous 'thing' throughout this article. That can be a tool, skill, technology, language, method or anything else in that vein.

As premise, you can think of somebody who just started with web development, picked a framework, looked at tutorials and just stumbled upon a problem related to the framework which is not covered in the tutorial.
When I started on that path, the most common course of action was googling the issue and copying the code block from the first StackOverflow answer.
Today its probably to ask ChatGPT or similar tools and just apply their answer, or even letting agents do the pasting, which is worse in my opinion, since a human on StackOverflow probably did put at least some thought into their answer, while current "AIs" aren't even capable of thinking, let alone critical thinking.

Immediate Effect

At best, it does what the person wants it to do and only that.
Or it might result in technical debt, needlessly complex or even plainly wrong architecture, or even a wrong understanding, which will be harder to correct the longer it is left unchecked.

The actual Result

When you start working with something new, and you only search for solutions and apply them, then you're not skipping ahead on the learning curve, but you rather delay your climb.

If you only ever see a question and the answer then you are only getting tiny spots of the whole picture which leaves a lot of room for interpretation which typically results in wrong assumptions.
Those wrong assumptions will manifest in bloated processes, technical debt and scuffed architecture amongst other things.
It will even stunt the development of your actual knowledge because at first you waddle through, which will anchor those wrong assumptions deeper and when you finally hit a point where you do realise, that you've been working under false pretences, you'll have to unlearn these first.
All of those effects will get worse the longer they compound.

So when you apply something you don't understand, you might not only have to deal with its immediate side effects which you might not even see at the current moment, but you will also have to deal with the knowledge gaps and their compounding consequences, throughout your career.

Examples

• Thinking that .env files get read directly by your program/process.
  • What actually happens: When you execute process.env['VARIABLE_NAME'] (JavaScript way to read environment variables) it never reads a file. The file is only used by Docker, or whatever tool you are using to run your program, to create the actual environment variables which will be assigned to the process and process.env['VARIABLE_NAME'] reads it from there.
    Same applies to any other programing language.
  • Anecdote: this happened to me a couple of times while helping out fellow programmers. They describe their development setup where they configure the program via an .env file, and they ask how to configure a (Docker) container. After I linked the appropriate documentation on how to set environment variables they proceeded to ask how those should be read by their program.
• Complex Maven pom.xml files
  • Anecdote: I've been working on many Maven(a JVM build system) projects throughout the years and I feel like most sufficiently complex projects reach the point where nobody really knows what does what and why in there.
    I think this is due to its plugin system, its build lifecycle system, the fact that it's configured through XML, and of course the state of the documentation.
    This is why I moved to Gradle with the Kotlin DSL. Build system configuration through code in a familiar language, and, at least in my case, often even the project language, makes it much more workable and coherent to me.
    And while the state of the gradle documentation isn't great either, it's a hell of a lot better than maven.
• Using the sledgehammer method to fix anything.
  • Anecdote: I've once helped someone with a Docker issue, and he was running docker system prune in between running docker-compose up. By his own admission it was to rebuild the image. I gave him the hint that he can also use docker-compose up --build to rebuild the images. You can also use docker-compose build.
• Confusing the IDE and build system
  • The actual situation: A build system is used to compile, bundle, package and publish a piece of software, among other things, since most build systems tend to be infinitely extensible. Think maven, gradle, esbuild, cargo, or dotnet build.
    It is generally an integral part of the project and available for the same platforms as the language.
    An IDE on the other hand, is just the tool you use to facilitate your development - A text editor with extras -, which might even be platform specific. IDEs typically come with integrations for build systems of the languages they are targeting, which probably is the source of the confusion, but there are also those rare cases where projects are relying on IDE internal build systems like the Intellij build system.
    However, I would advise to use a standalone build system because this allows you, and everyone else involved, to freely choose your IDE/editor, OS, and CI/CD setup.
  • Anecdote: I experienced this to be a common misconception for beginners. I had colleagues that weren't developers by trade but wrote some code who held this belief and I probably held it myself at some point when I started getting into development.
• Thinking Kubernetes namespace are a way to isolate deployments from each other
  • The actual situation: Namespaces in a vanilla cluster are 'only' to provide "a mechanism for isolating groups of resources within a single cluster." This means that "by default, all pods in a Kubernetes cluster are allowed to communicate with each other, and all network traffic is unencrypted."
    Anyone working with Kubernetes should be acutely aware of this.
    Of course there are ways to implement namespace isolation through built in methods like networking policies or more advanced options like cilium, but that's not the default.
  • Anecdote: In the DevOps exchange group of our company unit we were conversing about our dev stage Kubernetes setup and Kubernetes in general. We talked about namespace isolation to avoid ingress host duplication, wich can be done with a Kubernetes Policy Engine, what also led to discussing the lack of pod/service isolation by namespaces where we discovered that a good chunk of us wasn't aware of that.
    I can really recommend those targeted exchange groups to facilitate knowledge transfer within your company.

How to 'fix' it

Understand what you are working with, actually read the explanation that comes to most answers and take your time when learning new stuff, because you cannot waste time learning, since there is no useless knowledge.
And I actually mean that. Any piece of information you learn will help in completing the bigger picture. In general but especially in tech.
Read the documentation and articles, experiment (leave the beaten path/tutorial), ask questions to yourself and to other people, and generally challenge your ideas and concepts but especially if they are unclear in the slightest bit.
If you are looking for a community, to ask questions and to challenge your ideas, you can head over to The Programmers Hangout, a great Discord community for programmers and other techies.
A community of actual people is better than asking ChatGPT or similar tools because an actual person will think the problem through, alongside you, and so will be able to help you find the answer on your own, or catch wrong assumptions, you are having, which has a much greater learning effect than using an AI which will just spit out an answer.
AI tools also are still just glorified text generators which don't actually think and are known to hallucinate details, because they don't even have a concept of correctness.
So you should only use them for things where you actually know better and can correct their mistakes.
They are a great tool, not a great teacher.

Of course, you can't invest an endless amount of time into everything, so you'll also have to learn to gauge how deeply you have to learn a particular thing.
This is a skill you will pick up as you learn new things.
If you are helping someone, and you have the feeling, that they should invest more into learning that thing for their task at hand, then tell them, in order to help with the gauging process, and maybe even give them guidance onto what end, you think, they should continue with the given topic.

Be vigilant and keep your peers vigilant.
Perfection doesn't exist and avoiding snake oil is a continual process.
So use slip-ups to educate each other in a kind and productive manner.
Give explanations instead of just answers.

Thanks to my colleagues at crossnative for assisting in the creation of this article.