Capitalisation: The Hill Your App Will Die On
Ah caps. The most lovely thing in the world for actual copywriting… and simultaneously the demon lurking in every app build, just waiting to turn your "it works on my machine" moment into a full-blown production meltdown.
All because of an import statement.
We've all been there (please don't tell me it's just me): working on an app on your local Mac or Windows machine, deploying happily, and then boom – the production site goes belly-up with an error like "cannot find this file". But why? You didn't change anything… right?
Well, this is your friendly neighbourhood dev telling you: it was probably capitalisation. And this is why naming conventions matter. A lot.
This actually just happened to me recently – an AI-based update borked a personal dev site because a single file path used the wrong case. And yes, I knew better. But I did it anyway. Thankfully it was a personal site (read: I could care less on my own personal projects about proper CI/CD Protocols), and I had a backup ready. Living that chaotic "bugger it, we test in prod" energy. If you're a junior dev reading this: do as I say, not as I do. This is horrendous practice and I would never pull this on a client's project.
Let's talk about why this happens. And bring in our old frenemy: Linux.
File Systems, Baby
Windows and macOS (by default) run on case-insensitive file systems (NTFS and APFS respectively). This means MyFile.php, myfile.php, and MYFILE.php all point to the same damn file. Bless their hearts.
But Linux? Linux don't play.
Linux (most likely ext4) is case-sensitive. That means MyFile.php and myfile.php are completely different files. This is why your code can run just fine locally on your Windows machine but then combust in production, which is very likely Linux-based (and very unforgiving).
In fact, Linux powers about 96.3% of the top 1 million web servers, and over 70% of all web servers globally. Yeah. Odds are, if you're deploying to prod, you're deploying to Linux. So maybe… write your code like it?
The worst part? This isn't some deep, obscure bug. It's just you importing Helpers/Auth.php as helpers/auth.php, and your prod server promptly throwing a 500 error while you sit there staring into the abyss wondering how a capital 'H' just ruined your entire day.
Real-World Breakage: Laravel + Python Edition
Let's bring in some classic gotcha moments I've personally seen (and caused):
Laravel: PHP Autoloading Misery
// Actual file: app/Foo/Bar/SomeObject.php
$object = new \App\Foo\Bar\someObject(); // Wrong case in class name
This works on Windows. Laravel autoloads like a champ. But on Linux? Your app is toast. You'll get something like Class not found. Why? Because someObject ≠ SomeObject on a case-sensitive file system. Your class won't autoload. Your app won't boot.
Laravel uses PSR-4 autoloading, which is basically a fancy way of saying: "We expect the file path and class name to match exactly – including case – or we riot." (Okay, not riot. But it will fail silently in production and you'll cry.)
Python: The Silent Import Killer
# File is named mymodule.py
import MyModule # Windows: fine. Linux: ImportError
That ImportError? That's Linux saying: "Try again, sunshine."
This one's especially evil because it's so easy to overlook. You won't even see it until you're deploying or running on a Linux CI pipeline. Shout out to the CI server for catching what your IDE didn't.
Naming Conventions: Pick One and Stick to It
Okay so now that we know capitalisation is evil, how do we prevent future breakdowns?
Here's what I swear by (when I'm being responsible):
File and folder names? All lowercase. Always. (Seriously, it's not 2005 – we don't need
My-Fancy-Capitalised-Folder/)Use
snake_caseorkebab-casedepending on your framework.Class names? PascalCase (aka StudlyCaps – Laravel loves this)
Constants? ALL_CAPS, shouty snake style.
Variables and functions? camelCase (Laravel) or snake_case (Python)
Most importantly: whatever you pick, enforce it across your team.
Yes, even Chad the front-end dev who "doesn't like rules." This is how bugs sneak in, Chad.
Also? Don't have MyClass.php and myclass.php in the same repo. That's just asking for pain and broken imports that'll only show up in prod, three weeks from now, at 3am, when you're on call.
Tools and Tips
Use a linter – ESLint, PHP-CS-Fixer, flake8, whatever. If it can yell at your casing inconsistencies, let it.
Test on Linux (or WSL) – If you're on Windows and never test in a Linux-like environment, you're playing bug roulette.
Docker everything – If your local matches prod, fewer demons spawn.
CI/CD pipelines – Make sure they're case-sensitive (hint: most are if running Linux containers). Let CI catch the oopsies before your client does.
Bonus points if you add file case validation to your PR reviews. Because no one wants to die on the hill of Auth.js vs auth.js.
Final Word: You Will Get Burned. Once.
This is one of those things you don't fully appreciate until it bites you – hard. Usually at 11:47 PM before a client presentation. Just know: you only make this mistake once. After that, your naming will be tighter than PSR-12.
Treat casing like you treat semicolons – with respect and mild fear.
Name your files right. Match your imports. Run your CI. And for the love of all things syntactic: code like your server gives a damn about capital letters. Because it does.
So yeah. Capitalisation: the hill your app will die on. Unless you're smart enough to avoid it.
You've been warned.