Comments and Documentation

Documenting your scripts is always a very good idea. After all, the script makes perfect sense now, but will you be able to figure out what it's doing a year, or even a couple of months, from now?

For example, examine the script in Listing 3.2. See if you can figure out what the various portions of the script are doing.

Listing 3.2. AddUsersFromXLS.vbs. This script auto-creates users from an Excel spreadsheet.

Set oCN = CreateObject("ADODB.Connection")

oCN.Open "Excel"

Set oRS = oCN.Execute("SELECT * FROM [Sheet1$]")

Set oDomain = GetObject("WinNT://NT4PDC")

Set oFSO = CreateObject("Scripting.FileSystemObject")

Set oTS = oFSO.CreateTextFile("c:\passwords.txt",True)

sHomePath = "\\iridis1\c$\users\"

Do Until oRS.EOF

sUserID = oRS("UserID")

sFullName = oRS("FullName")

sDescription = oRS("Description")

sHomeDir = oRS("HomeDirectory")

sGroups = oRS("Groups")

sDialIn = oRS("DialIn")

sPassword = Left(sUserID,2) & DatePart("n",Time) & _

DatePart("y",Date) & DatePart("s",Time)

Set oUserAcct = oDomain.Create("user",sUserID)

oUserAcct.SetPassword sPassword

oUserAcct.FullName = sFullName

oUserAcct.Description = sDescription

oUserAcct.HomeDirectory = sHomeDir

If sDialIn = "Y" Then

oUserAcct.RasPermissions = 9

Else

oUserAcct.RasPermissions = 1

End If

oUserAcct.SetInfo

Set oUserAcct = GetObject("WinNT://NT4PDC/" & sUserID & ",user")

oTS.Write sUserID & "," & sPassword & vbCrLf

sGroupList = Split(sGroups, ",")

For iTemp = 0 To uBound(sGroupList)

Set oGroup = GetObject("WinNT://NT4PDC/" & _

sGroupList(iTemp) & ",group")

oGroup.Add oUserAcct.ADsPath

Set oGroup = Nothing

Next

Set oFolder = oFSO.CreateFolder(sHomePath & sUserID)

Set oUserAcct = Nothing

oRS.MoveNext

Loop

oRS.Close

oTS.Close

WScript.Echo "Passwords have been written to c:\passwords.txt."

It's a bit tough to follow, isn't it? Now look at Listing 3.3.

Listing 3.3. AddUsersFromXLS.vbs. This script auto-creates users from an Excel spreadsheet.

' PART 1: Open up the Excel spreadsheet

' using ActiveX Data Objects

Dim oCN

Set oCN = CreateObject("ADODB.Connection")

oCN.Open "Excel"



Dim oRS

Set oRS = oCN.Execute("SELECT * FROM [Sheet1$]")





' PART 2: Get a reference to the

' Windows NT domain using ADSI

Dim oDomain

Set oDomain = GetObject("WinNT://NT4PDC")





' PART 3: Open an output text file

' to store users' initial passwords

Dim oFSO, oTS

Set oFSO = CreateObject("Scripting.FileSystemObject")

Set oTS = oFSO.CreateTextFile("c:\passwords.txt",True)





' PART 4: For each record in the recordset,

' add the user, set the correct user

' properties, and add the user to the

' appropriate groups



' create the necessary variables

Dim sUserID, sFullName, sDescription

Dim sHomeDir, sGroups, sDialIn

Dim sPassword, oUserAcct, oFolder

Dim sGroupList, iTemp, oGroup



' define the base path for the home

' directories to be created in

Dim sHomePath

sHomePath = "\\iridis1\c$\users\"



' now go through the recordset one

' row at a time

Do Until oRS.EOF

  ' get the user information from this row

  sUserID = oRS("UserID")

  sFullName = oRS("FullName")

  sDescription = oRS("Description")

  sHomeDir = oRS("HomeDirectory")

  sGroups = oRS("Groups")

  sDialIn = oRS("DialIn")



  ' make up a new password

  sPassword = Left(sUserID,2) & DatePart("n",Time) & _

   DatePart("y",Date) & DatePart("s",Time)



  ' create the user account

  Set oUserAcct = oDomain.Create("user",sUserID)



  ' set account properties

  oUserAcct.SetPassword sPassword

  oUserAcct.FullName = sFullName

  oUserAcct.Description = sDescription

  oUserAcct.HomeDirectory = sHomeDir



  ' set RAS permission

  If sDialIn = "Y" Then

    oUserAcct.RasPermissions = 9

  Else

    oUserAcct.RasPermissions = 1

  End If



  ' save the account

  oUserAcct.SetInfo



  ' get a reference to the new account

  ' this gets us a valid SID & other info

  Set oUserAcct = GetObject("WinNT://NT4PDC/" & _

   sUserID & ",user")



  ' write password to file

  oTS.Write sUserID & "," & sPassword & vbCrLf



  ' PART 4A: Add user account to groups

  ' use the Split function to turn the

  ' comma-separated list into an array

  sGroupList = Split(sGroups, ",")



  ' go through the array and add the user

  ' to each group

  For iTemp = 0 To uBound(sGroupList)



    ' get the group

    Set oGroup = GetObject("WinNT://NT4PDC/" & _

     sGroupList(iTemp) & ",group")



    ' add the user account

    oGroup.Add oUserAcct.ADsPath



    ' release the group

    Set oGroup = Nothing



  Next





  ' PART 4B: Create the user's Home Directory

  ' (append UserID to the Home Path variable)

  Set oFolder = oFSO.CreateFolder(sHomePath & sUserID)





  ' PART 5: All done!

  ' release the user account

  Set oUserAcct = Nothing



  ' move to the next row in the recordset

  oRS.MoveNext



Loop





' PART 6: Final clean up, close down

oTS.CloseoRS.Close

WScript.Echo "Passwords have been written to c:\passwords.txt."

The scripts in Listings 3.2 and 3.3 will execute and do the exact same thing, but the one in 3.3 is much, much easier to figure out. Here's why.

• Comment lines (those beginning with the ' character) are included throughout, explaining what each section of the script is doing.

• The lines of code are indented, making it easy to see which blocks will be repeated in loops.

• White space in the form of blank lines is used to help break up the script and make different sections stand out more readily from one another.

As you can see from these examples, documentation and commenting isn't required, but it sure is nice. VBScript doesn't care about documentation and commenting, but you sure will if you ever have to work with a script that doesn't have it!