Best coding practices

2014-03-20T11:08:03Z

Prime03: /* Scopes of Variables */

Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.

A few notes:
* "(ND)" stands for "Not decided", meaning that the writer decided himself the best coding practice and it has to be validated by another MVP/a Developer.
* You must use the latest beta to run the below examples.

__TOC__

== Names of Variables ==
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it's simplified and regroup all the types of numbers in one type.

{| class="wikitable"
|-
! prefix !! covering type !! initialization
|-
| i || Numbers (any type) || $i = 0
|-
| a || Arrays || $a = 0 or $a[0]
|-
| s || Strings (chars included) || $s = ""
|-
| f || Booleans || $f = False or $f = True
|-
| b || Binaries || $b = ""
|-
| h || Handles (and GUI handles) || $h = 0
|-
| k (ND) || Keywords || Null (ND)
|-
| fu (ND) || Functions || Null (ND)
|-
| p || Pointers || $p = 0
|-
| tag || Structures definition || $tag = "somedef"
|-
| t || Structures || $t = 0
|-
| o || Objects || $o = 0
|-
| v || Various || $v = 0 or $v = "" (or $v = Null)
|}

The variables are named following this schema:
{| class="wikitable"
|-
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)
|-
| i || f || MyFlag
|}

Example:
<syntaxhighlight lang="autoit">
; Assign a Local variable the number 5.
Local $iSomeVar = 5

; Assign a Local variable the number 1.
Local $ifMyFlag = 1

; Assign a Local variable an array of numbers.
Local $aiArray = 0

; Re-declare the array to size and fill it.
Local $aiArray[3] = [0, 0.25, 3 / 4]
</syntaxhighlight>

Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local $iSomeVar1, $aiArray = 0
Local $iSomeVar2 = 5

;Good
Local $iSomeVar1 = 0, $iSomeVar2 = 5
Local $aiArray = 0
</syntaxhighlight>
You can still categorize your variables and declare for example the $iSomeVar2 on another line.

Example2:
<syntaxhighlight lang="autoit">
#include <Constants.au3>

Local $vValue ; Bad, this is initially blank.
Local $vVal = 0 ; Good

MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)

; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt
; is a little less forgiving in that it initialises the variable as being blank and doesn't throw any error, unlike some moder C++ compilers.
</syntaxhighlight>

== Scopes of Variables ==
To make the transition, the variables are also named according to their scope.
{| class="wikitable"
|-
! Global UDF variable !! Global variable !! Local variable
|-
| $__iSomeVar or $g__iSomeVar || $_iSomeVar or $g_iSomeVar || $iSomeVar
|}
With this method, you will avoid non wanted re-assignments.

Example:
<syntaxhighlight lang="autoit">
#include <MessageBoxConstants.au3>

; Assign a Global variable the number 0.
Global $iSomeVar1 = 0
; Assign a Global variable the number 5.
Global $_iSomeVar2 = 5

_SomeFunc()

Func _SomeFunc()
; Assign Local variables respectively the numbers 3 and 4.
Local $iSomeVar1 = 3, $iSomeVar2 = 4

; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".

; Display the value of $iSomeVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)

; Display the value of $iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)

; Display the value of $_iSomeVar2.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)
EndFunc
</syntaxhighlight>

* A variable declared globally (with the Global keyword) is visible anywhere in the script.
Always declare your global variables in the global scope, not in the functions. It will prevent another function to use it before its declaration and the declaration is implicit (see [[#jumpsec1|examples]]).

* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.
:Declaration in the global scope: the variable is nonetheless visible everywhere; declare it as Local if this one is only used in the same scope.
:Declaration in a function: the variable is visible by the function itself and nowhere else.

Structure of a code scope:
<syntaxhighlight lang="autoit">
; Global scope.

; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).
#include <MessageBoxConstants.au3>

; This scope is either Global or Local, depending on where do you use the variables.

; Assign a Global variable the number 0 (which corresponds to an initialization of a variable number), its scope is Global because it's used at least in one function.
Global $_iVar1 = 0

; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.
Local $_sVar2 = "foo"

; Display the content of $_sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)

; Re-assign a Local variable the string returned by the function _MyFunc1.
$_sVar2 = _MyFunc1()

; Re-Display the content of $_sVar2
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)

; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).
Func _MyFunc1()
; Local scope.

; Display the content of $_iVar1.
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)

; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.
Local $sVar3 = "bar"

; Display the content of $sVar3.
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)

; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.
Return $sVar3
EndFunc
</syntaxhighlight>

Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).

Example 1:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function.
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5.
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].
Local $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

; Empty the array (and keep its size).
Dim $aArray[5]

; Display the contents.
_ArrayDisplay($aArray)
</syntaxhighlight>
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.

Example 2:
<syntaxhighlight lang="autoit">
#include <Array.au3>

; Call _MyFunc1 with default parameters ($vParam1 = 0).
_MyFunc1()

; Assign a Local variable an array containing integers.
Local $aiArray[3] = [3, 4, 5]
; Call _MyFunc1 with $aiArray as parameter ($vParam1 = $aiArray).
_MyFunc1($aiArray)

Func _MyFunc1($vParam1 = 0)
; If $vParam1 is NOT an array then redeclare it to an array.
If IsArray($vParam1) = 0 Then
Dim $vParam1[3] = [0, 1, 2]
EndIf

; Display the array.
_ArrayDisplay($vParam1)
EndFunc ;==>_MyFunc
</syntaxhighlight>

And for the ReDim keyword, limit its use to resize an array you want to keep its content:
<syntaxhighlight lang="autoit">
; Include the Array UDF, it's needed here for the _ArrayDisplay function.
#include <Array.au3>

; Assign a Local variable an array containing numbers with a size of 5.
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].
Local $aArray[5] = [1, 2, 3, 4, 5]

; Display the contents.
_ArrayDisplay($aArray)

; Resize the array (and keep its content).
ReDim $aArray[3]

; Display the contents.
_ArrayDisplay($aArray)
</syntaxhighlight>

Why using Dim over Local/Global is not always a good option:
<syntaxhighlight lang="autoit">
#include <MessageBoxConstants.au3>

Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."

MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")

Example()

Func Example()
MsgBox($MB_SYSTEMMODAL, "", $vVariableThatIsGlobal) ; That looks alright to me as it displays the following text: This is a variable that has "Program Scope" aka Global.

Local $vReturn = SomeFunc() ; Call some random function.

MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".
EndFunc ;==>Example

Func SomeFunc()
; This should create a variable in Local scope if the variable name doesn"t already exist.
; For argument sake I totally forgot that I declared a variable already with the same name.
; Well I only want this to be changed in the function and not the variable at the top of the script.
; Should be OK right? Think again.
Dim $vVariableThatIsGlobal = ""

For $i = 1 To 10
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.
Next
Return $vVariableThatIsGlobal
EndFunc ;==>SomeFunc
</syntaxhighlight>

<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span>
<syntaxhighlight lang="autoit">
#include <MessageBoxConstants.au3>

; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.
; Now look at Example 2.
Example()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.
EndFunc ;==>SomeFunc
</syntaxhighlight>

Example 2:
<syntaxhighlight lang="autoit">
#include <MessageBoxConstants.au3>

; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable
; $vVariableThatIsGlobal contains.
SomeFunc()

Func Example()
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'
SomeFunc()
EndFunc ;==>Example

Func SomeFunc()
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."
EndFunc ;==>SomeFunc
</syntaxhighlight>

Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:
<syntaxhighlight lang="autoit">
#include <MessageBoxConstants.au3>

; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.
For $i = 1 To 10 ; $i is in 'loop scope.'
Local $iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.
</syntaxhighlight>

<syntaxhighlight lang="autoit">
#include <MessageBoxConstants.au3>

; Declaring variables outside of loops is more efficent in the long run.
Local $iInt = 0
For $i = 1 To 10 ; $i is in 'loop scope.'
$iInt = $i
Next
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.
</syntaxhighlight>

There is no requirement to declare the iteration count variable in a loop:
<syntaxhighlight lang="autoit">
; Correct
Local Const $iCount = 99
Local $aArray[$iCount]
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.
$aArray[$i] = $i
Next

; Incorrect
Local Const $iCount = 99
Local $aArray[$iCount]
Local $i ; This is only used to store the iteration count value in the loop and therefore doesn't need to be declared. This is known as loop scope.
For $i = 0 To UBound($iCount) - 1
$aArray[$i] = $i
Next
</syntaxhighlight>
As you can see, there is the Const keyword in the example, we are going to talk about it.

== Const, Static, Enum ==

=== Const ===
We won't talk about the advantages of a constant variable, they are neglibible (for your information, an autoit constant variable is marked as read-only and remains a variable as read-only when compiled).

The Const keyword may be used in a first by some of you to avoid re-assignments.
The best way to use them is not this last case, the constants should be used for real static variables, meaning that their value won't change regardless to the instance of the program.

Example:
<syntaxhighlight lang="autoit">
;Bad
Local Const $hGUI = GUICreate("MyGUI")
; The handle of the window is unique, it's generated by Windows and changes.

;Good
Local Const $iMyAge = 19
</syntaxhighlight>

=== Static ===
Static variables are the solution to the global variables used in only one function.
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.
<syntaxhighlight lang="autoit">
Example()

Func Example()
SomeFunc() ; This will display a message box of 1, 1.
SomeFunc() ; This will display a message box of 1, 2.
SomeFunc() ; This will display a message box of 1, 3.
EndFunc ;==>Example

Func SomeFunc()
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be
; accessed from anywhere else in the script apart from the Function it was declared in.
Local Static $vVariableThatIsStatic = 0
Local $vVariableThatIsLocal = 0
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.
$vVariableThatIsStatic += 1 ; This will increase by 1.
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)
EndFunc ;==>SomeFunc
</syntaxhighlight>

=== Enum ===
This statement is often practical in certain situations:
<syntaxhighlight lang="autoit">
#include <MessageBoxConstants.au3>

Example()

Func Example()
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.

; Create an array in Local scope with 4 elements.
Local $aAnimalNames[4]

; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]

; Display the values of the array.
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)

; Sometimes using this approach for accessing an element is more practical than using a numerical value, due to the fact changing the index value of
; the enum constant has no affect on it's position in the array. Therefore changing the location of $eCat in the array is as simple as changing the order
; it appears in the initial declaration e.g.

; Local Enum $eDog, $eMouse, $eCat, $eHamster

; Now $eCat is the 2nd element in the array. If you were using numerical values, you would have to manually change all references of $aAnimalNames[0] to
; $aAnimalNames[2], as well as for the other elements which have now shifted.
EndFunc ;==>Example
</syntaxhighlight>

== Au3Check directive ==
As you may know (and we hope), the Au3Check tool checks your code for syntax errors, variables used without being declared etc. which is a good thing to fix your script.

With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:
<syntaxhighlight lang="autoit">
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
</syntaxhighlight>

== Magic Numbers ==
Magic numbers are arbitrary numbers interspersed throughout a program's source code which do not have an associated identifier. The downside to this is not being able to derive a meaning from the number.

For example:
<syntaxhighlight lang="autoit">
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")
</syntaxhighlight>
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.

Example 2:
<syntaxhighlight lang="autoit">
; Imagine you're a new user to AutoIt and you come across this code, where would you find -3, -4 or -5 in the help file?
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean
; why would you, the help file is there for a reason.
Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case -3 ; Doesn't really tell much about what it does.
ExitLoop

Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?
MsgBox(4096, '', 'Do something when this action takes place.')

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

Did you understand the numbers were these:
<syntaxhighlight lang="autoit">
#include <GUIConstantsEx.au3>

Example()

Func Example()
Local $hGUI = GUICreate('')
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.
GUISetState(@SW_SHOW, $hGUI)

While 1
Switch GUIGetMsg()
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.
ExitLoop

Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.

EndSwitch
WEnd

GUIDelete($hGUI)
EndFunc ;==>Example
</syntaxhighlight>

[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]

More coming soon :)

AutoIt Wiki - User contributions [en]

Best coding practices