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

1. 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
2. Always validate input:
   prepare for the unexpected
3. Doublequote command line arguments, e.g. "%~1" instead of %1
4. 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
5. Consistent casing:
   whether you prefer upper case or lower case for commands, switches, etcetera, it doesn't really matter — but be consistent
6. Initialize your variables:
   a supposedly "new" variable may have been defined already
7. Use local variables, or reset all variables you introduced before exiting
8. 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)
9. 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 ...
10. Start each command in a code block on a new line, properly indented
11. 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
12. When using external commands, check their availability and version
13. Specify extensions for external commands:
    avoid confusion between executables and scripts sharing the same name
14. If possible, specify the full paths for external commands
15. Debug your batch files, even if they already seem to function properly

DON'Ts

1. Don't use variables for command names if you can avoid it:
   commands hidden in variables make debugging your batch files so much harder
2. Don't nest IF ... ELSE ... if you can avoid it
3. Don't nest code blocks if you can avoid it:
   use subroutines instead for improved maintainability
4. 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
5. 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!
6. 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."