Bat File Coding Standard

[A proposed coding standard for Microsoft MsDos/Windows batch files. (Similar to UnixShell scripts.)]

It's really frustrating to read a BAT file. Usually it's not indented, capitalization varies etc. The following is an attempt to formalize some standards for BAT files.

• All batch file names should start with a capital letter followed by small letters and capitalising the beginning of each word thereafter.

• All batch file names should be nouns.

• All batch files should contain header regarding the purpose of the batch file and the command line arguments it expects in proper formatted way as shown below. Just above this, it should contain @echo off so that the code of the batch file is not shown to the user!

@echo off
rem ***********************************************************************
rem This bat file makes the JAR library files out of the source files.
rem This expects the following format
rem call LibMaker -name <jarName> -root <-pkgRoot> *[subPackages]
rem -name            Name of the JAR file including the extension
rem -root            The package root
rem *subPackages     Any number of sub-packages that you need to compile 
rem                  into this JAR.
rem ***********************************************************************

• Batch files do not place any restrictions on the case. It is suggested that you use lower case for coding batch files since lower case code is easier to read. The code inside a label segment should be indented.

E.g.

:init
     call SetupEnv

     if not "%1"=="-name" goto noPkgName
     shift
     set _PKG_NAME=%1
     shift

     if not "%1"=="-root" goto noRootPkg
     shift
     set _PKG_ROOT=%1
     shift

:cleanUp
     set _PKG_ROOT=

• It's suggested that all the code segments be placed inside a label segment as much as possible since this helps in identifying what exactly that code segment is doing. (Treat it like a function call!)

• In case of a normal batch file, it should contain label segments finish and cleanUp. And it must be ensured that all the variables that are set, be cleaned up when their use is over. If it's formalized then it's easier to search for these sections in a large bat file.

• In general, use "SetupEnv.bat" to set up the global variables and end the batch file execution by call-ing "CleanupEnv.bat". Both the files should be created if they do not already exist. This way, we limit the changes that occur to the global variables to a single file and thus can be edited easily.

• All the global variable names that are required only for the current execution of the batch file set should start with "_". This is to ensure that variable name conflicts does not occur.

Please add to the standards more useful ones. -- VhIndukumar.

These generally seem like good ideas. But "All batch file names should be nouns"? Don't you want your batch files to do something? Given the example header, doesn't this batch file "MakeLibrary"? -- JeffGrigg

That header is fundamentally broken - if you echo that information out (standardizing the switch used), you get all of the benefits of keeping that information in the source file and the benefits of making it available to the users. -- DanilSuits

How safe is it to use the cmd extensions that you get in NT or 2K? In particular, setlocal/endlocal does what SetUpEnv.bat and CleanupEnv.bat would do. There's is an excellent book on cmd scripts that I go and find the title of.

I've used the extensions extensively and had no problems, the ability to use do subroutines is very handy as well as the extensions to the set command.

Is the book Windows NT Shell Scripting, I had it once, but lent it to someone, it is excellent

I think it's a good idea to standardize the switches. Probably the following will be useful. The code can check if the user has not given any input or has typed "/?"

:help
    echo call LibMaker -name <jarName> -root <-pkgRoot> *[subPackages]
    echo -name            Name of the JAR file including the extension
    echo -root            The package root
    echo *subPackages     Any number of sub-packages that you need to compile 
    echo                  into this JAR.

-- VhIndukumar

"@echo off" is an AntiPattern, because the script cannot restore the echoing to its previous state, and because it can accidentally be toggled by echoing nothing. -- JasperPaulsen

See DosPatterns

--- several undocumented, though not uncommon things are case sensitive in Windows Command scripts. ss64 dot com has several examples, one of which is when using the FOR construct: "Format letters are case sensitive in Windows 2000 and above, so using a capital letter is also a good way to avoid conflicts %%A rather than %%a"