We use this at my place, though in bash, and we call it executable documentation.
Stuff like:
NAME="$1"
# Create directory for the code
mkdir "$NAME"
# Checkout the source
cd $NAME && git something
# and so on
Sometimes with an
echo "You need to read and understand this before just using it"; exit 1 thrown in somewhere for good measure.
These files will have no logic, and make very little use of variables. They will also have a .txt filename to ensure that people understand, that first of all, this is a set of instructions for how to do something, which just so happens to be a valid bash script.
We embed similar explanatory docs in Markdown. A short example for dig from our troubleshooting guide:
# General form
dig @<resolver> <record>
dig @1.1.1.1 www.example.com
# Omit the resolver to use the system's configured resolvers
dig www.example.com
# Don't need the full output?
dig +short www.example.com
This sounds like basically what I use READMEs or supplementary Markdown documentation files for, just in a bash code block in a Markdown file rather than in a bash file.
That's true. I guess I tend to just use those as examples/documentation at the start, and then when I want to automate the process, I do it more in an all-at-once way (with a Python project or something) rather than incremental additions to a bash script. Do-nothing scripting does definitely sound like a technique I should try out. I'm not a huge fan of bash for stuff beyond a list of short commands/steps, though.
NAME="$1"
# Create directory for the code
mkdir "$NAME"
# Checkout the source
cd $NAME && git something
# and so on
Sometimes with an echo "You need to read and understand this before just using it"; exit 1 thrown in somewhere for good measure.
These files will have no logic, and make very little use of variables. They will also have a .txt filename to ensure that people understand, that first of all, this is a set of instructions for how to do something, which just so happens to be a valid bash script.