Batch File Best Practices
DOs and DON'Ts When Writing Batch Files
Batch files may be a convenient way to "glue" commands together, thus easily automating repetitive tasks, they can also be a pain in the [beep] if you have to maintain them.
If you think understanding someone else's batch files can be hard, try maintaining them, it can be a real nightmare!
To allow easier (I did not say "easy"!) maintenance, there are some simple rules to be followed:
DOs
- Add comments:
tell what the code was meant to do, what input it expects, what results are to be expected; and include a change log
- Always validate input:
prepare for the unexpected
- Doublequote command line arguments, e.g.
"%~1"
instead of %1
- Doublequote paths:
spaces, ampersands or parenthesis in paths may not only break your code, they can even pose a security threat, as the September 2014 code insertion vulnerability disclosure made painfully clear
- Consistent casing:
whether you prefer upper case or lower case for commands, switches, etcetera, it doesn't really matter — but be consistent
- Initialize your variables:
a supposedly "new" variable may have been defined already
- Use local variables, or reset all variables you introduced before exiting
- When using subroutines, pass the relevant data as arguments, instead of relying on "global" variables:
this makes reusing your code in other batch files so much easier (but don't forget to validate the input in the subroutine)
- Always use multi-line, indented code blocks (parenthesis) in
IF
statements or FOR
loops, e.g.
IF "%~1"=="/?" (
...
) ELSE (
...
)
instead of
IF "%~1"=="/?" (...) ELSE (...)
— or even worse: IF "%~1"=="/?" ... ELSE ...
- Start each command in a code block on a new line, properly indented
- Give each command its own dedicated line:
avoid "one-liners" (multiple command lines joined into a single one by ampersands), or at least be aware that they imply a code block
- When using external commands, check their availability and version
- Specify extensions for external commands:
avoid confusion between executables and scripts sharing the same name
- If possible, specify the full paths for external commands
- Debug your batch files, even if they already seem to function properly
DON'Ts
- Don't use variables for command names if you can avoid it:
commands hidden in variables make debugging your batch files so much harder
- Don't nest
IF ... ELSE ...
if you can avoid it
- Don't nest code blocks if you can avoid it:
use subroutines instead for improved maintainability
- Don't use
@command
to hide command echoing, except @ECHO OFF
in the first line:
hiding command echoing makes debugging your batch files so much harder
- Don't use "one-liners" (multiple command lines joined into a single one by ampersands), or at least be aware that they imply a code block:
using code blocks, with each command on its own dedicated line, makes debugging so much easier!
- Don't use "clever" tricks and "quick and dirty" shortcuts if you can avoid them, or thoroughly document them in the source code:
"Debugging is always harder than programming, so if you write code as cleverly as you know how, by definition you will be unable to debug it."
page last modified: 2024-03-18; loaded in 0.0015 seconds