Companies are built of many projects and repositories. Each tends to develop its own culture and tools for interacting with it.
The client is compiled with MSVC, and tests are run with
./runner.py --test foo/bar/baz_test.py.
The website builds with SCons and tests are run with
The utility library has
Over time, some projects put scripts in the root, some in
bin, maybe some in a directory named
scripts. Some projects might use all three.
This makes it hard for people coming to the project to know 1) how to do common project tasks and 2) what the set of available commands even is.
When code is collectively owned and engineers contribute across the entire stack, it’s important that anyone can easily check out a repository and start developing in it, no matter the language or tooling.
At IMVU we solved this problem by introducing a directory to every project named
- How do you build the project?
- How do you run the tests?
- How do you deploy?
- How do you lint?
- How do you launch the program?
- What if there’s a server component?
- How do you see what commands are available?
At first there was some resistance, primarily to the name. “s is too short. Nobody will know what it means.” But after living with it, it was perfect:
- It’s short.
- It’s on home row for both qwerty and dvorak.
sdoesn’t already have a semantic meaning.
bin, for example, is often used for programs generated by the build script. Conflating that with project tooling is confusing.
s is a home only for project commands – the interface that developers use to interact with the project. These commands should use the same nomenclature as your company (e.g. if people say build, call it s/build; if people say compile, call it s/compile).
The scripts shouldn’t have extensions, because, importantly, the programming language is an implementation detail. That is,
s/build.py are wrong.
s/build lets you be consistent across projects and have the option to migrate from Python to Bash or whatever.
s/ is a simple trick, but it goes a long way towards helping people migrate between projects!