File Naming Conventions
There is no single "correct" naming convention — but the choices below hold up well across operating systems, tools, and years of a growing folder.
Why filenames matter
A good filename is a tiny piece of documentation: it tells you what a file is without opening it, sorts sensibly next to related files, and survives being copied between Windows, macOS, and a web server without breaking.
Spaces vs. hyphens vs. underscores
Hyphens (product-photo.jpg) are the safest default — readable, URL-friendly, and never misread as an escape character. Underscores work almost as well. Spaces are the riskiest choice: some tools and URLs encode them as "%20" or break on them entirely.
Lowercase filenames
macOS and Windows treat filenames as case-insensitive by default, but Linux servers do not — "Photo.jpg" and "photo.jpg" are different files there. Lowercase everything and you sidestep the mismatch entirely.
Special characters
Avoid < > : " / \ | ? * and control characters — they're invalid on Windows and cause problems in URLs and shells even where the filesystem allows them. Accented letters (é, ü, ñ) are valid but worth normalizing (café → cafe) for maximum compatibility.
Filename length
Keep filenames under roughly 255 characters, and in practice much shorter. Long names are usually a symptom of packing metadata into the name — a naming pattern with clear fields does that job better.
Sequential numbering
Pad numbers with leading zeros (001, 002 … not 1, 2) so files sort correctly once you pass nine or ninety-nine items. Three digits comfortably covers most batches.
Dates in filenames
Use ISO 8601 order — YYYY-MM-DD — so filenames sort chronologically as plain text: report-2026-03-01.pdf sorts correctly next to report-2026-04-12.pdf without any special handling.
Version naming
Prefer an explicit, sortable version marker — contract-v2.pdf or contract-2026-03-01.pdf — over "final", "final final", or "final v2", which carry no reliable ordering information.
Naming images
Combine a descriptive base name with sequential numbering: product-blue-shirt-001.jpg. Descriptive names also help with image SEO, since search engines read the filename.
Naming product files
Include the stable identifier your systems already use — a SKU or product ID — alongside a human-readable name: sku-48213-blue-shirt.jpg keeps files matchable to a catalog even after a product is renamed.
Naming documents
A pattern like 2026-03-01-invoice-acme-corp.pdf front-loads the date for sorting and keeps the document type and party identifiable at a glance, without opening the file.
Naming for developers
Match the casing convention your tooling expects — kebab-case for URLs and most config files, snake_case for Python modules, camelCase only where the language or framework requires it — and stay consistent within a project.