Put files where they are expected

Reeds on a beach. A kite is flying in the sky behind them.

When creating a new file for your programming project, how do you choose how to name it and where to put it?

I recommend choosing a location that is expected by both humans and programs. Here are a couple of examples:

README. There’s a decades-long convention of putting the basic overview documentation for a project in a file called README. This convention is now recognized by tools: for example, GitHub renders it in the repository front page.

Docker Compose. If you use docker-compose to set up the development environment, you could put its configuration file with a custom name in some subdirectory and use docker-compose -f path/to/my/config-file… or you could put it in docker-compose.yml in repository root and ignore the -f parameter. Then docker-compose up would be enough to start the dev environment.

Clojure tests. When you create tests for your Clojure project, you could name them arbitrarily… or you could put tests for the namespace a.b.c in a.b.c-test and you can enjoy using Projectile’s and Cursive’s “jump between test and implementation” feature. Cursive even has a nice feature for creating new tests, but it assumes this naming convention.

If you do what the humans expect, they don’t have to ask questions or look up the documentation. If you do what the programs expect, they’re more ergonomic to use.

Comments or questions? Send me an e-mail.