For a while now, I have had the mindset that any high-level operation related to a software project should be captured as an OS-native script kept either in the repo's root directory or an appropriate subdirectory. For example, the following scripts are located in the root directory of my blog repo:
_Build_HTML.bat_Cleanup.bat_Deploy_SSH.bat_Run_Test_Server.bat
A few things worth noting about the filenames alone:
- The scripts are Windows-native batch files since Windows is my primary OS.
- The operations performed by each script should be clear from the name alone.
- The leading underscore allows all scripts to be easily grouped together.
- The
Mixed_Case_With_Underscoresconvention should set the scripts apart from other files.
At the very least, many of my projects have a _Build_All.bat (or similar) and _Cleanup.bat script in the root directory. These tend to be a bit more user-friendly than makefiles alone. The ability to run the scripts directly from Windows Explorer or the command shell is also helpful. Even if the scripts simply call a makefile, I would rather have them there.
Originally, I limited this naming convention to only OS-native scripts. However, recently I started adopting the convention to scripts written in other languages such as Python. It makes identifying standalone (i.e. not a library or part of a larger application) scripts easy; guess which of these scripts performs a standalone operation: foobar.py or _Do_Something_Cool.py.
Some guidelines I follow for naming these scripts:
- One leading underscore.
- First word should be a strong verb that describes the action of the script (e.g. build, copy, cleanup, move, etc).
- The first letter of each word should be capitalized.
- Acronyms should be capitalized appropriately.
- Keep the script name short; no more than three words.
- Separate words with underscores.
I have a structured template for what these types of scripts typically contain but those details will have to wait for another post.
