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.