Consistent File and Directory Naming

Why Naming Is Part of Project Organization

A file name is a small piece of project documentation. A well-chosen name helps a collaborator identify what an artifact is for, how it relates to other artifacts, and whether it is ready for a particular use. A weak name transfers that work to memory or to a separate explanation. Names such as analysis_new2.R, config_final.yaml, and run_latest do not reliably communicate purpose or status: their meaning depends on who created them and when.

Consistent naming is not a substitute for separating source files, inputs, and generated artifacts. It complements that organization by making items within each part of a project easier to recognize and compare. A useful convention should be predictable, readable, and stable enough that a name does not need to change every time someone revises a comment or reruns an analysis.

Build Names From Stable, Meaningful Fields

Before choosing separators or capitalization, decide what a reader needs to know from the name. A typical name can be built from a small set of fields: artifact type, analysis purpose or scope, and—when needed—a date, version, or status. Put the fields in a consistent order. If one script begins with its purpose and another similar script begins with its date, both may be individually understandable, but the collection is harder to scan and sort.

This is a design pattern, not a requirement that every name contain every field. Include a field only when it distinguishes artifacts in a useful way. For example, a single analysis-plan document may not need a date in its name if the project already identifies the relevant plan version elsewhere. Conversely, two configuration files for different analysis populations may need the population in their names to prevent accidental substitution.

Prefer words that a new team member can interpret without asking the original author. Use the same term for the same concept across scripts, configurations, documentation, and run folders. If the project calls a population “evaluable” in one name and “per-protocol” in another, readers may reasonably infer that they differ. Abbreviations are useful only when they are established, unambiguous within the project, and applied consistently. Initials, personal names, and locally invented shorthand tend to be less durable.

Choose a separator and capitalization pattern, then apply it throughout the project. Lowercase words separated by underscores or hyphens are easy to distinguish visually; either can work if used consistently. Avoid relying on capitalization alone to distinguish two files, because some filesystems treat names that differ only by letter case as equivalent. Keep the actual file extension intact, and do not add punctuation that some tools or operating systems interpret specially. Detailed path portability is a separate concern, but conservative names reduce avoidable friction.

Dates, Versions, and Status Need Different Jobs

Dates are useful when they identify a time-specific artifact, such as a frozen data delivery or a dated report. Use an unambiguous order such as year-month-day, with leading zeros where needed: 2026-10-27 sorts chronologically as text when all dates use the same format. A date should describe the artifact’s relevant date, not be added automatically to every source file. A script that is continually maintained may become misleading if its name retains the date on which it was first created.

A version number is useful when people must distinguish intentional revisions of a controlled artifact. Use one pattern, such as v01, v02, and v03, rather than mixing v2, revisionB, and second_update. Incrementing a version communicates that a distinct revision exists; it does not by itself explain what changed or establish that the newer version is scientifically preferable. Version naming should therefore follow the project’s actual review and change-control practices.

Status is different from identity. An artifact’s identity answers “which item is this?”; its status answers “what state is it in now?” Define a short, controlled vocabulary before using status terms. For example, draft, review, and approved can be meaningful if the team defines who assigns them and what each permits. Terms such as final, latest, and done are weak labels: “final” often becomes outdated, “latest” changes over time, and “done” does not say whether an item was reviewed.

Status can change more often than an artifact’s identity. If changing status requires renaming a file used by scripts or referenced in documentation, the label may create broken references or make old copies hard to interpret. For a working artifact, it can be safer to keep its stable name and record its current status in an appropriate project record. A status term in a filename can be useful for a frozen, distributed snapshot, provided the label has a defined meaning and the snapshot is not silently overwritten.

Run Folder Names: Identify the Run Without Hiding Its State

A run folder name should help distinguish one execution from another and convey the purpose or scope needed for recognition. A useful pattern can combine a date, a unique sequence or identifier, and a concise purpose, for example run_20261027_003_base_model. The date is in year-month-day order, the sequence distinguishes runs on the same date, and “base_model” communicates purpose. The sequence must be assigned consistently; otherwise two folders could receive the same name.

Whether status belongs in a run folder’s name depends on how that folder will be used. If a folder is a fixed snapshot prepared for a particular review state, a controlled suffix such as review or approved can clarify its intended state. If the status changes during work, renaming the folder can undermine references to it. In that case, preserve the run’s stable identifier and record the changing status separately. Do not use names such as run_latest or run_final as substitutes for unique run identity.

Check a Convention Before Adopting It

A naming convention works only if people can apply it and if its names distinguish the artifacts that matter. A short review can expose weaknesses before many files depend on the pattern. The reasoning is straightforward: names are useful when a reader can infer the intended identity, and identity requires enough distinguishing information. If two different artifacts map to the same name, or if a field’s meaning changes between names, the convention has failed that purpose.

Useful diagnostics include repeated names with different meanings, a collection in which similar artifacts follow different word orders, and status labels that have no agreed definition. Another warning sign is a name whose meaning can only be recovered from a person’s memory. These are not cosmetic problems: they make selection and review more error-prone, especially when multiple files have similar content.

There are alternatives to descriptive names, but each has trade-offs. A short numeric identifier can be compact and unique, yet tells a reader little without a lookup record. A long prose-like filename can be explicit, but becomes cumbersome and may duplicate information available elsewhere. A useful convention balances recognizable meaning against unnecessary length. It does not attempt to put every detail of an analysis into the filename.

Naming conventions have limits. They cannot prove that a script implements its stated purpose, that a configuration matches a model, or that a run is reproducible. Names also cannot replace records of substantive changes or review decisions. The aim is narrower and practical: make names informative enough to support correct recognition, while keeping identity, status, and detailed documentation from being confused with one another.