Coding Standards for AutoIt Good Code

Developers in your company surely stick to a single coding standard that was developed on their own with regard for area of specialization or using one of ready solutions, as there are a number of them for popular programming languages.

There are no ready solutions for AutoIt language yet. It’s because, at first, its modest functionality gave the possibility only to automate frequently repeated tasks in Windows environment and not to develop function-rich programs. That is why the question of standardization was not topical.

But nowadays the language enjoys wide popularity for its class of tasks and increases the possibilities it provides. That is why we propose the readers the standard we worked out in our company. You can use it entirely or adapt to your requirements.

The article is intended for specialists of test automation, their managers and also for those whose tasks are writing of scripts (macros) for automation of tasks in Microsoft Windows environment with the use of AutoIt language.

Advantages of Usage of a Single Standard
Standard of Writing of Scripts
Static Analysis as Means of Code Improvement
Example
Conclusion

Advantages of Usage of a Single Standard

Coding standard (standard of code design) is a set of rules and agreements that are used when writing the source code in a certain programming language.

Rules of program element visual design that are used for the increase of self-descriptiveness of the code for a man form the basis of any standard.

Such rules include the description of a method of choosing the names for program identifiers (variables, function), usage of indents and arrangement of brackets when designing logical blocks, comment style, etc.

It is generally known that the usage of a single code design standard guarantees some advantages:

Better code readability (as a result, decrease of time resources required for its understanding)
Simplification of code support, process of making changes in it
Simplification of test integration
Simplicity of code reuse
Decrease of communications

Thus, having decided to standardize automatic testing procedures, you will be able to enjoy all the advantages mentioned above. The main advantage is that the company will reduce time resources on automation (and as a result, financial resources too).

Standard of Scripts Writing

Standards for Visual Basic (as AutoIt is a BASIC family language), requirements to User Defined Functions of AutoIt language, and agreements that define the code of high quality independently of the programming language were taken as a basis when developing the current standard.

Names of Variables, Constants, and Functions

Register

Use CamelCasing for names of variables and functions and UPPER_CASING for constants. The use of the CamelCasing technique implies that words in the name are connected and differed by the use of capital letters. Thus, whitespaces, underlining, and dash symbol are forbidden for using in names of variables and functions.

Good:

$ReceivedError

Bad:

$received_error

Reference to data type

After the dollar sign (“$”), from which the declaration of a variable starts, there must be a symbol or a set of symbols that defines what type of data it will contain.

You can use the following list of prefixes:

$a<Letter>	Array. Letter points to the type of data stored in array
$b	Binary data
$h	File or window handle
$i	Integer
$f	Boolean
$n	Floating point number
$s	String
$v	Unknown beforehand or variable type of data

Significant names

In the next part of the name, use words pointing what the variable (function) is intended for.

Good:

$asEmployeesNames

Bad:

$iQwerty

Declaration of Variables and Functions

Variables

Two approaches are possible here: declaration of all variables in the beginning of a script or directly before their usage. In my opinion, the first variant is more convenient. But it’s your right to choose the one :).

Functions

If we can allocate the repeated part of the code to a function in the auto-test body, this function is located:

in the beginning of the script after the main comment if a function is significant and frequently called (for example, the function of system restart if the restart is performed several times in the process of test run).
at the end of the script if the function performs insignificant actions (for example, work with GUI).

Indents

Standard AutoIt editor of the SciTE Script Editor code (http://www.autoitscript.com/site/autoit-script-editor/) uses 4 spaces in the tab. That is why we will take 4 spaces as a basis.

Use the tab of four symbols when writing any statement of decision-making:

Conditional statement (If…Then…Else; Select…Case; Switch…Case)
Cycle statement (For…Next; While…WEnd; Do…Until; For…In…Next)

Good:

If $fTemperature > 38.5 Then
    MsgBox (4096, "", "You need a doctor.")
ElseIf $ fTemperature > 37.5   Then
    MsgBox(4096, "", "You catch a cold.")
Else
    MsgBox(4096, "",  "Everything is Ok.")
EndIf

Bad:

Switch @HOUR
Case 6 To 11
$sGreatMsg = "Good Morning"
Case 12 To 17
$sGreatMsg = "Good Afternoon"
Case 18 To 21
$sGreatMsg = "Good Evening"
Case Else
$sGreatMsg = "What are you still doing up?"
EndSwitch

If you decided to use another number of symbols in a tab, reset your code editor to avoid loss of time on manual formatting.

For SciTE Script Editor, go to Options -> Indentation Settings or press Ctrl+Shift+I

Spaces

Use of spaces improves the code readability significantly.

Surround each statement with one space and also add space after comma.

Good:

$nSalary = 20 + 20

Bad:

$nSalary=20+20

Comments

We can single out comments of two types: script level and in-line comments.

Script level comments

Each separate script must begin with a block comment (#comments-start … #comments-end) that can include the following information: the author of the script, what the script performs, what the input and output parameters are, history of changes (optionally),and also a link to documents (for example, requirements specification in case if the script implements an auto-test for the check of a certain requirement. As a result, traceability improves and making of changes is simplified).

Good:

#comments-start
 Author  
Tom Brown
-----
What the test should do
It should install Google Chrome on the machine
-----
Parameters
Input: Path to installation package
#comments-end

Bad:

#comments-start
#comments-end

In-line comments

With the help of in-line comments, you help yourself or your colleague who is involved in code support to remember/understand what a certain construction means/is responsible for.

In-line comment can be located above, below, and in the same line with the commented construction. In my opinion, it is more convenient to place the comment above the statement.

Good:

;Print all numbers from 1 to 10 except number 7
For $i = 1 To 10
    If $i = 7 Then ContinueLoop
        MsgBox(0, "The value of $i is:", $i)
Next

Bad:

For $i = 1 To 10
    If $i = 7 Then ContinueLoop
        MsgBox(0, "The value of $i is:", $i)
Next

Static Analysis and Code Review as Tools of Code Improvement

Correspondence of the code to a certain standard can be checked with the help of two techniques of static analysis: with the help of technical review or use of special utilities (static analyzers) whose add-ons help to add standard rules and check correspondence to them (for more information about techniques of static testing, see [Graham, Van Veenendaal, Evans, Black “Foundations of Software testing”]).

Unfortunately, static analyzers for AutoIt language were not found in the process of work and writing of this article. That is why the only possible solution at the current moment is the adoption of code review practice.

Team review for automation scripts is redundant. As a rule, it is enough to perform a pair review when one (reraly, several) technical specialist is involved in code review.

In the process of review, the responsible specialist uses the internal coding standard and a check list created on its basis. All found drawbacks are fixed and sent to the author for correction.

In the result of code analysis:

The code quality increases due to detection and correction of departure from the standard (that makes the code more readable, simple for understanding and support)
Skills of the code author improve

Example

A piece of code, designed without using any standard:

#include <FTPEx.au3>
$server = '192.168.0.202'
$port = '300'
$username = ''
$pass = ''
$Open = _FTP_Open('FTP')
$Conn = _FTP_Connect($Open, $server, $username, $pass, '1',$port)
$Remote = '/Storage/Utilites/GoogleChrome7/'
_FTP_DirSetCurrent($Conn, $Remote);
$a= _FTP_ProgressDownload($Conn, @DesktopDir & 'ChromeSetup.exe', 'ChromeSetup.exe')
MsgBox(4096,"Warning!","Close opened Firefox and IE browser windows to continue installation or they will be closed automatically in 5 sec. If Google Chrome is installed - it will be reinstalled",5)
If @OSVersion = "Win_7" Then
DirRemove(@UserProfileDir & 'AppDataLocalGoogle',1)
EndIf
If @OSVersion = "Win_XP" Then
DirRemove(@UserProfileDir & 'AppDataLocalGoogle',1)
EndIf
if ProcessExists("firefox.exe") Then
ProcessClose("firefox.exe")
EndIf
if ProcessExists("iexplore.exe") Then
ProcessClose("iexplore.exe")
EndIf
if ProcessExists("chrome.exe") Then
ProcessClose("chrome.exe")
EndIf
Run(@DesktopDir & 'ChromeSetup.exe')
WinWaitActive("Google Chrome installer")
WinWaitClose("Google Chrome installer")
WinWaitActive("Welcome to Google Chrome")
ControlClick("Welcome to Google Chrome", "Choose","[Class:Button; INSTANCE:4]")
WinWaitActive("Google - Google Chrome")
WinClose("Google - Google Chrome")
FileDelete(@DesktopDir & 'ChromeSetup.exe')
_FTP_Close($Open)

A piece of code, designed using a standard described in the current article:

#comments-start
Author  
Tom Brown
-----
What the test should do
Test automates Google Chrome installation on local machine
-----
Creation Date
2011-03-26
#comments-end
include <FTPEx.au3>
$sServer = '192.168.0.202'
$sPort = '300'
$sUsername = ''
$sPass = ''
; Get Chrome installation package from a common location
$vOpen = _FTP_Open('FTP')
$vConn = _FTP_Connect($Open, $server, $username, $pass, '1',$port)
$vInstallationLocation = '/Storage/Utilites/GoogleChrome7/'
_FTP_DirSetCurrent($Conn, $Remote);
$vStatus= _FTP_ProgressDownload($Conn, @DesktopDir & 'ChromeSetup.exe', 'ChromeSetup.exe')
MsgBox(4096,"Warning!","Close opened Firefox and IE browser windows to continue installation or they will be closed automatically in 5 sec. If Google Chrome is installed - it will be reinstalled",5)
; Delete previously installed Google Chrome temp file
If @OSVersion = "Win_7" Then
    DirRemove(@UserProfileDir & 'AppDataLocalGoogle',1)
EndIf
If @OSVersion = "Win_XP" Then
    DirRemove(@UserProfileDir & 'AppDataLocalGoogle',1)
EndIf
if ProcessExists("firefox.exe") Then
    ProcessClose("firefox.exe")
EndIf
if ProcessExists("iexplore.exe") Then
    ProcessClose("iexplore.exe")
EndIf
if ProcessExists("chrome.exe") Then
    ProcessClose("chrome.exe")
EndIf
Run(@DesktopDir & 'ChromeSetup.exe')
WinWaitActive("Google Chrome installer")
WinWaitClose("Google Chrome installer")
WinWaitActive("Welcome to Google Chrome")
ControlClick("Welcome to Google Chrome", "Choose","[Class:Button; INSTANCE:4]")
WinWaitActive("Google - Google Chrome")
WinClose("Google - Google Chrome")
FileDelete(@DesktopDir & 'ChromeSetup.exe')
_FTP_Close($Open)

Conclusion

Usage of a single standard as well as introduction of formalism into the process in any other way should not be an end in itself. But its usage gives significant results, especially on the stage of code support. Thus, insignificant increase of resources when creating the code (additional time for review and correction of comments) gives you such benefits as possible reuse of the code (integration of separate parts of auto-test to other tests) and also easier modifications (that is inevitable as the product is liable to frequent changes in the process of development and testing).