https://www.autoitscript.com/w/api.php?action=feedcontributions&feedformat=atom&user=CzardasAutoIt Wiki - User contributions [en]2026-04-03T18:49:36ZUser contributionsMediaWiki 1.43.6https://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12933Best coding practices2015-03-15T11:16:33Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452<br />
|}<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Inconsistent data types are considered bad.<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Correct initialization<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Default Value !! covering type<br />
|-<br />
| Binary("") || $d<br />
|-<br />
| "" || $s, $v<br />
|-<br />
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v<br />
|-<br />
| 0.0 || $f<br />
|-<br />
| Null || $o, $s, $v<br />
|-<br />
| False (or True) || $b<br />
|}<br />
<br />
<br /><br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Declare and initialize a variable with the recommended default value.<br />
Local $vUndefined = Null ; This does not require much memory.<br />
<br />
; Some time later:<br />
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed.<br />
</syntaxhighlight><br />
<br /><br />
<br />
To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; Recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
Variables should also be named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
; Recommended<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12932Best coding practices2015-03-15T11:11:47Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Constant variable || Local Const $eEulersConstant = 2.7182818284590452<br />
|}<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Inconsistent data types are considered bad.<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Correct initialization<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Default Value !! covering type<br />
|-<br />
| Binary("") || $d<br />
|-<br />
| "" || $s, $v<br />
|-<br />
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v<br />
|-<br />
| 0.0 || $f<br />
|-<br />
| Null || $fu, $o, $s, $v<br />
|-<br />
| False (or True) || $b<br />
|-<br />
| Default || $k<br />
|}<br />
<br />
<br /><br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Declare and initialize a variable with the recommended default value.<br />
Local $vUndefined = Null ; This does not require much memory.<br />
<br />
; Some time later:<br />
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed.<br />
</syntaxhighlight><br />
<br /><br />
<br />
To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; Recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
Variables should also be named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
; Recommended<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12931Best coding practices2015-03-15T11:05:28Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Constant variable || Enum $e1st = 1, $e2nd, $e3rd<br />
|}<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Inconsistent data types are considered bad.<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Correct initialization<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Default Value !! covering type<br />
|-<br />
| Binary("") || $d<br />
|-<br />
| "" || $s, $v<br />
|-<br />
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v<br />
|-<br />
| 0.0 || $f<br />
|-<br />
| Null || $fu, $o, $s, $v<br />
|-<br />
| False (or True) || $b<br />
|-<br />
| Default || $k<br />
|}<br />
<br />
<br /><br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Declare and initialize a variable with the recommended default value.<br />
Local $vUndefined = Null ; This does not require much memory.<br />
<br />
; Some time later:<br />
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed.<br />
</syntaxhighlight><br />
<br /><br />
<br />
To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; Recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
Variables should also be named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
; Recommended<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12930Best coding practices2015-03-15T11:00:22Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|}<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Inconsistent data types are considered bad.<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Correct initialization<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Default Value !! covering type<br />
|-<br />
| Binary("") || $d<br />
|-<br />
| "" || $s, $v<br />
|-<br />
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v<br />
|-<br />
| 0.0 || $f<br />
|-<br />
| Null || $fu, $o, $s, $v<br />
|-<br />
| False (or True) || $b<br />
|-<br />
| Default || $k<br />
|}<br />
<br />
<br /><br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Declare and initialize a variable with the recommended default value.<br />
Local $vUndefined = Null ; This does not require much memory.<br />
<br />
; Some time later:<br />
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed.<br />
</syntaxhighlight><br />
<br /><br />
<br />
To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; Recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
Variables should also be named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
; Recommended<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12929Best coding practices2015-03-15T09:45:40Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
'''Note''': You must use AutoIt v3.3.10.0 or above to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Inconsistent data types are considered bad.<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Correct initialization<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Default Value !! covering type<br />
|-<br />
| Binary("") || $d<br />
|-<br />
| "" || $s, $v<br />
|-<br />
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v<br />
|-<br />
| 0.0 || $f<br />
|-<br />
| Null || $fu, $o, $s, $v<br />
|-<br />
| False (or True) || $b<br />
|-<br />
| Default || $k<br />
|}<br />
<br />
<br /><br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Declare and initialize a variable with the recommended default value.<br />
Local $vUndefined = Null ; This does not require much memory.<br />
<br />
; Some time later:<br />
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed.<br />
</syntaxhighlight><br />
<br /><br />
<br />
To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; Recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
Variables should also be named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
; Recommended<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12920Best coding practices2015-03-10T12:09:37Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Inconsistent data types are considered bad.<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Correct initialization<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
In the following table, recommended default values are shown for each data type. Some data types have more than one possibile default value which can be used for initialization.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Default Value !! covering type<br />
|-<br />
| Binary("") || $d<br />
|-<br />
| "" || $s, $v<br />
|-<br />
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v<br />
|-<br />
| 0.0 || $f<br />
|-<br />
| Null || $fu, $o, $s, $v<br />
|-<br />
| True (or False) || $b<br />
|-<br />
| Default || $k<br />
|}<br />
<br />
<br /><br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Declare and initialize a variable with the recommended default value.<br />
Local $vUndefined = Null ; This does not require much memory.<br />
<br />
; Some time later:<br />
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed.<br />
</syntaxhighlight><br />
<br /><br />
<br />
To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; Recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
; Recommended<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12919Best coding practices2015-03-10T12:08:38Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Inconsistent data types are considered bad.<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Correct initialization<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
In the following table, recommended default values are shown for each data type. Some data types have more than one possibile value which can be used for initialization.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Default Value !! covering type<br />
|-<br />
| Binary("") || $d<br />
|-<br />
| "" || $s, $v<br />
|-<br />
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v<br />
|-<br />
| 0.0 || $f<br />
|-<br />
| Null || $fu, $o, $s, $v<br />
|-<br />
| True (or False) || $b<br />
|-<br />
| Default || $k<br />
|}<br />
<br />
<br /><br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Declare and initialize a variable with the recommended default value.<br />
Local $vUndefined = Null ; This does not require much memory.<br />
<br />
; Some time later:<br />
$vUndefined = 0xB0AD1CEA ; Assign an appropriate value as and when needed.<br />
</syntaxhighlight><br />
<br /><br />
<br />
To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; Recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
; Recommended<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12918Best coding practices2015-03-10T11:27:39Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $tSTRUCT = DllStructCreate($tagSTRUCT)<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by assigning data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Inconsistent data types are considered bad.<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Correct initialization<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
In the following table, recommended default values are shown for each data type. Some data types have more than one possibile value which can be used for initialization.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Default Value !! covering type<br />
|-<br />
| Binary("") || $d<br />
|-<br />
| "" || $s, $v<br />
|-<br />
| 0 || $a, $h, $i, $id, $m, $n, $o, $p, $t, $tag, $v<br />
|-<br />
| 0.0 || $f<br />
|-<br />
| Null || $fu, $o, $s, $v<br />
|-<br />
| True (or False) || $b<br />
|-<br />
| Default || $k<br />
|}<br />
<br />
<br /><br />
To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; Recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Not recommended<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
; Recommended<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12909Best coding practices2015-03-08T04:34:52Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Inconsistent data types are considered bad.<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; correct initialization<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to follow, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12908Best coding practices2015-03-08T04:09:46Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Bad because of inconsistent data types<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Good<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to read, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12907Best coding practices2015-03-08T04:08:14Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If for some reason you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Bad because of inconsistent data types<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Good<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
To reduce bloat, multiple variables can be declared on a single line. When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to read, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12906Best coding practices2015-03-08T02:57:27Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! dollar prefix !! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| $ || a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If for some reason you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Bad because of inconsistent data types<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Good<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to read, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idBtnGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idBtnQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12905Best coding practices2015-03-08T02:10:44Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If for some reason you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Bad because of inconsistent data types<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Good<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to read, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idBtnGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idBtnQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12904Best coding practices2015-03-08T02:09:59Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If for some reason you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Bad because of inconsistent data types<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Good<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to read, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idBtnGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idBtnQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. Regarding data types, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12903Best coding practices2015-03-08T01:42:54Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If for some reason you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Bad because of inconsistent data types<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Good<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
When declaring multiple variables on the same line, it is generally recommended that you stick to declaring one data type on each line. The intention here is to make the code easier to read, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idBtnGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idBtnQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. As regards type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12902Best coding practices2015-03-08T01:37:47Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br /><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If for some reason you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Bad because of inconsistent data types<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Good<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
<br />
When declaring multiple variables on the same line, it is a general recommendation that you stick to declaring one data type on each line. The intention here is to make the code easier to read, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idBtnGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idBtnQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br /><br />
<br />
In some languages it is essential to initialize variables on declaration, but this is not the case with AutoIt. As regards type, variables declared without being initialized should be considered as being undefined.<br />
<br /><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12901Best coding practices2015-03-08T01:12:59Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If for some reason you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Bad because of inconsistent data types<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
; Good<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br /><br />
When declaring multiple variables on the same line, it is a general recommendation that you stick to declaring one data type on each line. The intention here is to make the code easier to read, however the best layout will vary according to circumstance.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; not recommended<br />
Local $sString = "", $iInteger = 0, $asArray = ["a","b","c"] ; Mixed data types<br />
<br />
; recommended<br />
Local $iLeft = 10, $iTop = 10 ; integers<br />
Local $idBtnGo = GUICtrlCreateButton("Go", $iLeft, $iTop), $idBtnQuit = GUICtrlCreateButton("Quit", 50, 10) ; controlIDs<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12900Best coding practices2015-03-08T00:28:07Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If for some reason you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad because of inconsistent data types<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
;Good<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12899Best coding practices2015-03-08T00:22:34Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If for some reason you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same (or the most logical representation of its) type and use as little memory as possible.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad because of inconsistent data types<br />
Local $iInteger = "0"<br />
Local $sString = False<br />
<br />
;Good<br />
Local $iInteger = 0<br />
Local $sString = ''<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12898Best coding practices2015-03-08T00:03:19Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If for some reason you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same type and use as little memory as possible.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12897Best coding practices2015-03-08T00:00:43Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
== Variable Initialization ==<br />
When initializing variables there are several points to consider. It is bad practice to hog memory by holding data which is not immediately required. It is therefore recommended that you declare and initialize variables immediately prior to use. If for some reason you wish to assign a default value to a variable which you intend to overwrite later, then the data should be of the same type.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12896Best coding practices2015-03-07T22:53:18Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
== Variable Initialization ==<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12895Best coding practices2015-03-07T22:35:04Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The variable naming convention used in AutoIt is based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12894Best coding practices2015-03-07T22:27:34Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
Variable naming conventions in AutoIt are based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12893Best coding practices2015-03-07T22:26:57Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do so.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
Variable naming conventions in AutoIt are based on [http://en.wikipedia.org/wiki/Hungarian_notation Apps Hungarian notation]. The prefix defines the logical data type rather than the physical data type: in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs during assignment. See the table below for accepted standards.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
Variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12892Best coding practices2015-03-07T22:02:25Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what are to be considered the best coding practices within AutoIt. These recommendations are based on accepted coding practices common to a number of other programming languages. You do not need to follow them, but it is recommended that you do so.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation defines the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12891Best coding practices2015-03-07T21:40:29Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation defines the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of strings.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12890Best coding practices2015-03-07T21:37:47Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation defines the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 0<br />
|-<br />
| a || Arrays || $aArray[0]<br />
|-<br />
| m || Maps || $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlID || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $pRect = DllStructGetPtr($tRECT)<br />
|-<br />
| tag || Structures definition || $tagDATE = "struct; word Year;word Month;word Dow;word Day; endstruct"<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $oShell = ObjCreate("shell.application")<br />
|-<br />
| v || Variant || $vData = ClipGet()<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| a || h || Handles<br />
|}<br />
<br />
Examples:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a local variable the integer 7.<br />
Local $iWeekDays = 7<br />
<br />
; Assign a local variable the value of Pi.<br />
Local $fPi = 3.14159265358979<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $asArray[7] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']<br />
<br />
; Assign a local variable an array of numbers.<br />
Local $anArray[4] = [0, 0.25, 3 / 4, 12]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
The corrected example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox($MB_TOPMOST, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12870Best coding practices2015-03-07T00:03:06Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation defines the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this occurs on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12869Best coding practices2015-03-07T00:00:09Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation defines the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this is done on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12868Best coding practices2015-03-06T23:59:10Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation strives to define the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this is done on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12867Best coding practices2015-03-06T23:34:20Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation strives to encode the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this is done on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $e1st = 1, $e2nd, $e3rd<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12866Best coding practices2015-03-06T23:32:10Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation strives to encode the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this is done on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $e1stValue = 1, $e2ndValue, $e3rdValue<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12865Best coding practices2015-03-06T23:31:17Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation strives to encode the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this is done on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $eFirstValue = 1, $eSecondValue, $eThirdValue<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12864Best coding practices2015-03-06T23:29:24Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation strives to encode the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this is done on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $eFirst = 1, $eSecond, $eThird<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12863Best coding practices2015-03-06T23:13:26Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation strives to encode the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type: this is done on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $eStartCount = 0, $eAddOne, $eAddTwo<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12862Best coding practices2015-03-06T23:08:28Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
A variant of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is used.<br /><br />
In AutoIt the Hungarian notation strives to encode the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type. This is done on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $eStartCount = 0, $eAddOne, $eAddTwo<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12861Best coding practices2015-03-06T23:02:25Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
The [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] is adopted however it has been simplified and regroup all the types of numbers in one type.<br /><br />
In AutoIt the Hungarian notation strives to encode the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type. This is done on assignment.<br /><br />
See the table below for examples.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $eStartCount = 0, $eAddOne, $eAddTwo<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12860Best coding practices2015-03-06T22:52:55Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
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.<br /><br />
In AutoIt the Hungarian notation strives to encode the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type.<br /><br />
Variables are initialized with the "default" value (or the most logical representation) of their type. See below in the table for specific value.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $eStartCount = 0, $eAddOne, $eAddTwo<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Best_coding_practices&diff=12859Best coding practices2015-03-06T22:51:51Z<p>Czardas: </p>
<hr />
<div>Outlined in this section is a detailed explanation of what is to be considered the best coding practices within AutoIt.<br />
<br />
<br />
A few notes:<br />
* You must use the latest version of AutoIt (v3.3.10.0 or above) to run the examples below.<br />
<br />
<br />
__TOC__<br />
<br />
== Names of Variables ==<br />
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.<br /><br />
In AutoIt the Hungarian notation strives to encode the logical data type rather than the physical data type; in this way, it gives a hint as to what the variable's purpose is, or what it represents. The prefix does not encode the actual data type.<br /><br />
Variables are initialized with the "default" value (or the most logical representation) of their type. See below in the table for specific value.<br />
<br />
{| class="wikitable"<br />
|-<br />
! prefix !! covering type !! example<br />
|-<br />
| i || Integer || $iInteger = 10<br />
|-<br />
| f || Floating point || $fFloat = 0.123<br />
|-<br />
| n || General number (no preference) || $nNumber = 123<br />
|-<br />
| a || Arrays || Local $aArray[0]<br />
|-<br />
| m || Maps || Local $mMap[]<br />
|-<br />
| s || Strings (chars included) || $sString = "hello world"<br />
|-<br />
| b || Booleans || $bBool = True<br />
|-<br />
| d || Binaries || $dBinary = Binary("0x80000000")<br />
|-<br />
| id || An AutoIt controlid || $idButton = GUICtrlCreateButton("OK", 5, 5)<br />
|-<br />
| h || Handles (and GUI handles) || $hGUI = GUICreate("My GUI")<br />
|-<br />
| fu || Functions || $fuMessage = MsgBox<br />
|-<br />
| p || Pointers || $p = 0<br />
|-<br />
| tag || Structures definition || $tag = 0<br />
|-<br />
| t || Structures || $t = 0<br />
|-<br />
| o || Objects || $o = 0 or $o = Null<br />
|-<br />
| v || Variant || $v = 0 or $v = "" (or $v = Null)<br />
|-<br />
| e || Enumerations || Enum $eBegin = 0, $eAddOne, $eAddTwo<br />
|-<br />
| k || Keywords || $kKeyword = Default<br />
|}<br />
<br />
<br />
The variables are named following this schema:<br />
{| class="wikitable"<br />
|-<br />
! type (lower case) !! [optional] subtype (lower case) !! var name (first letter in upper case)<br />
|-<br />
| i || f || MyFlag<br />
|}<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
; Assign a Local variable the number 5.<br />
Local $iSomeVar = 5<br />
<br />
; Assign a Local variable the number 1.<br />
Local $ifMyFlag = 1<br />
<br />
; Assign a Local variable an array of numbers.<br />
Local $aiArray = 0<br />
<br />
; Re-declare the array to size and fill it.<br />
Local $aiArray[3] = [0, 0.25, 3 / 4]<br />
</syntaxhighlight><br />
<br />
<br />
Always initialize a variable on it's declaration, and declare all the same type of variable on the same line.<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local $iSomeVar1, $aiArray = 0<br />
Local $iSomeVar2 = 5<br />
<br />
;Good<br />
Local $iSomeVar1 = 0, $iSomeVar2 = 5<br />
Local $aiArray = 0<br />
</syntaxhighlight><br />
You can still categorize your variables and declare for example the $iSomeVar2 on another line.<br />
<br />
Example2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Local $vValue ; Bad, this is initially blank.<br />
Local $vVal = 0 ; Good<br />
<br />
MsgBox($MB_SYSTEMMODAL, '', '$vValue: ' & $vValue & @CRLF & '$vVal: ' & $vVal)<br />
<br />
; In C++ $vValue would display the previous value that was residing in the memory address $vValue points to. AutoIt<br />
; 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.<br />
</syntaxhighlight><br />
<br />
== Scopes of Variables ==<br />
To make the transition, the variables are also named according to their scope.<br />
{| class="wikitable"<br />
|-<br />
! Global UDF variable !! Global variable !! Local variable<br />
|-<br />
| $g__iSomeVar || $g_iSomeVar || $iSomeVar<br />
|}<br />
With this method, you will avoid non wanted re-assignments.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Assign a Global variable the number 0.<br />
Global $iSomeVar1 = 0<br />
; Assign a Global variable the number 5.<br />
Global $_iSomeVar2 = 5<br />
<br />
SomeFunc()<br />
<br />
Func SomeFunc()<br />
; Assign Local variables respectively the numbers 3 and 4.<br />
Local $iSomeVar1 = 3, $iSomeVar2 = 4<br />
<br />
; Note: The user inadvertently re-assigned the global variable $iSomeVar1, because this one is not named as "global".<br />
<br />
; Display the value of $iSomeVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar1: " & $iSomeVar1)<br />
<br />
; Display the value of $iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $iSomeVar2: " & $iSomeVar2)<br />
<br />
; Display the value of $_iSomeVar2.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iSomeVar2: " & $_iSomeVar2)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
<br />
* A variable declared globally (with the Global keyword) is visible anywhere in the script.<br />
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]]).<br />
<br />
* A variable declared locally (with the Local keyword), has a visibility which depends of the scope where it's declared.<br />
: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.<br />
:Declaration in a function: the variable is visible by the function itself and nowhere else.<br />
<br />
<br />
Structure of a code scope:<br />
<syntaxhighlight lang="autoit"><br />
; Global scope.<br />
<br />
; Include the Constants file, it contains various constants; it's needed here for the $MB_SYSTEMMODAL flag of the MsgBox function).<br />
#include <MsgBoxConstants.au3><br />
<br />
; This scope is either Global or Local, depending on where do you use the variables.<br />
<br />
; 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.<br />
Global $_iVar1 = 0<br />
<br />
; Assign a Local variable the string "foo", its scope is Local because it's use is restricted to this scope.<br />
Local $_sVar2 = "foo"<br />
<br />
; Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Re-assign a Local variable the string returned by the function MyFunc.<br />
$_sVar2 = MyFunc()<br />
<br />
; Re-Display the content of $_sVar2<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar2: " & $_sVar2)<br />
<br />
; Declare a function (its main utility is described later in Functions, we can see one here which is to create a Local scope).<br />
Func MyFunc()<br />
; Local scope.<br />
<br />
; Display the content of $_iVar1.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $_iVar1: " & $_iVar1)<br />
<br />
; Assign a Local variable the string "bar", its scope is Local because it's use is restricted to the function's scope.<br />
Local $sVar3 = "bar"<br />
<br />
; Display the content of $sVar3.<br />
MsgBox($MB_SYSTEMMODAL, "", "Value of $sVar3: " & $sVar3)<br />
<br />
; Return the $sVar3 content, it will be visible (if used) to the scope where the function is called.<br />
Return $sVar3<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
Concerning the Dim keyword, its recommended usage is limited to empty an existing array (Example 1) or to redeclare a function parameter (Example 2).<br />
<br />
Example 1:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Empty the array (and keep its size).<br />
Dim $aArray[5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
Remark: The variable type of the emptied array is a string, every variable non initialized is a string.<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
<br />
; Call MyFunc with default parameters ($vParam1 = 0).<br />
MyFunc()<br />
<br />
; Assign a Local variable an array containing integers.<br />
Local $aiArray[3] = [3, 4, 5]<br />
; Call MyFunc with $aiArray as parameter ($vParam1 = $aiArray).<br />
MyFunc($aiArray)<br />
<br />
Func MyFunc($vParam1 = 0)<br />
; If $vParam1 is NOT an array then redeclare it to an array.<br />
If IsArray($vParam1) = 0 Then<br />
Dim $vParam1[3] = [0, 1, 2]<br />
EndIf<br />
<br />
; Display the array.<br />
_ArrayDisplay($vParam1)<br />
EndFunc ;==>MyFunc<br />
</syntaxhighlight><br />
<br />
<br />
And for the ReDim keyword, limit its use to resize an array you want to keep its content:<br />
<syntaxhighlight lang="autoit"><br />
; Include the Array UDF, it's needed here for the _ArrayDisplay function.<br />
#include <Array.au3><br />
<br />
; Assign a Local variable an array containing numbers with a size of 5.<br />
; Note than an array is based 0 index, to access the first element the code is: $aiArray[0].<br />
Local $aArray[5] = [1, 2, 3, 4, 5]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
<br />
; Resize the array (and keep its content).<br />
ReDim $aArray[3]<br />
<br />
; Display the contents.<br />
_ArrayDisplay($aArray)<br />
</syntaxhighlight><br />
<br />
<br />
Why using Dim over Local/Global is not always a good option:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."<br />
<br />
MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")<br />
<br />
Example()<br />
<br />
Func Example()<br />
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.<br />
<br />
Local $vReturn = SomeFunc() ; Call some random function.<br />
<br />
MsgBox($MB_SYSTEMMODAL, $vReturn, $vVariableThatIsGlobal) ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This should create a variable in Local scope if the variable name doesn"t already exist.<br />
; For argument sake I totally forgot that I declared a variable already with the same name.<br />
; Well I only want this to be changed in the function and not the variable at the top of the script.<br />
; Should be OK right? Think again.<br />
Dim $vVariableThatIsGlobal = ""<br />
<br />
For $i = 1 To 10<br />
$vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.<br />
Next<br />
Return $vVariableThatIsGlobal<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
<span id="jumpsec1">Declaring Global variables in a Function is never a good idea:</span><br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling Example() first will initialise the Global variable $vVariableThatIsGlobal and therefore calling SomeFunc() won't return an error.<br />
; Now look at Example 2.<br />
Example()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable was initialised this will not return an error.<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Calling SomeFunc() first will bypass the Global variable $vVariableThatIsGlobal being initialised and therefore AutoIt has no idea of what data the variable<br />
; $vVariableThatIsGlobal contains.<br />
SomeFunc()<br />
<br />
Func Example()<br />
; Declaring a variable in a function can cause serious problems, hence why all Global variables should be declared at the top of a script.<br />
Global $vVariableThatIsGlobal = 'This is a variable that has ''File Scope'' aka Global.'<br />
SomeFunc()<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
MsgBox($MB_SYSTEMMODAL, '', $vVariableThatIsGlobal) ; As the variable wasn't initialised this will return an error of "variable used without being declared."<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
Declaring variables in loops (For, While, Do etc..) can have an affect on efficiency:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables inside loops should be avoided as the variable is re-declared on each repetition.<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
Local $iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
; Declaring variables outside of loops is more efficent in the long run.<br />
Local $iInt = 0<br />
For $i = 1 To 10 ; $i is in 'loop scope.'<br />
$iInt = $i<br />
Next<br />
MsgBox($MB_SYSTEMMODAL, '', $iInt) ; This will display 10.<br />
</syntaxhighlight><br />
<br />
<br />
There is no requirement to declare the iteration count variable in a loop:<br />
<syntaxhighlight lang="autoit"><br />
; Correct<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
For $i = 0 To UBound($iCount) - 1 ; $i is only used in the loop, so there is no requirement to declare it.<br />
$aArray[$i] = $i<br />
Next<br />
<br />
; Incorrect<br />
Local Const $iCount = 99<br />
Local $aArray[$iCount]<br />
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.<br />
For $i = 0 To UBound($iCount) - 1<br />
$aArray[$i] = $i<br />
Next<br />
</syntaxhighlight><br />
As you can see, there is the Const keyword in the example, we are going to talk about it.<br />
<br />
== Const, Static, Enum ==<br />
<br />
=== Const ===<br />
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).<br />
<br />
The Const keyword may be used in a first by some of you to avoid re-assignments.<br />
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.<br />
<br />
<br />
Example:<br />
<syntaxhighlight lang="autoit"><br />
;Bad<br />
Local Const $hGUI = GUICreate("MyGUI")<br />
; The handle of the window is unique, it's generated by Windows and changes.<br />
<br />
;Good<br />
Local Const $iMyAge = 19<br />
</syntaxhighlight><br />
<br />
<br />
=== Static ===<br />
Static variables are the solution to the global variables used in only one function.<br />
e.g: Retain variable data once returned from a Function and only use that variable in that particular Function.<br />
<syntaxhighlight lang="autoit"><br />
Example()<br />
<br />
Func Example()<br />
SomeFunc() ; This will display a message box of 1, 1.<br />
SomeFunc() ; This will display a message box of 1, 2.<br />
SomeFunc() ; This will display a message box of 1, 3.<br />
EndFunc ;==>Example<br />
<br />
Func SomeFunc()<br />
; This initialises a Static variable in Local scope. When a variable is declared just in Local scope (within a Function,)<br />
; it's destroyed when the Function ends/returns. This isn't the case for a Static variable. The variable can't be<br />
; accessed from anywhere else in the script apart from the Function it was declared in.<br />
Local Static $vVariableThatIsStatic = 0<br />
Local $vVariableThatIsLocal = 0<br />
$vVariableThatIsLocal += 1 ; This will always be 1 as it was destroyed once returned from SomeFunc.<br />
$vVariableThatIsStatic += 1 ; This will increase by 1.<br />
MsgBox(4096, $vVariableThatIsLocal, $vVariableThatIsStatic)<br />
EndFunc ;==>SomeFunc<br />
</syntaxhighlight><br />
<br />
<br />
=== Enum ===<br />
This statement is often practical in certain situations:<br />
<syntaxhighlight lang="autoit"><br />
#include <MsgBoxConstants.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
; Create variables in Local scope and enumerate through the variables. Default is to start from 0.<br />
Local Enum $eCat, $eDog, $eMouse, $eHamster ; $eHamster is equal to the value 3, not 4.<br />
<br />
; Create an array in Local scope with 4 elements.<br />
Local $aAnimalNames[4]<br />
<br />
; Assign each array element with the name of the respective animal. For example the name of the cat is Jasper.<br />
$aAnimalNames[$eCat] = 'Jasper' ; $eCat is equal to 0, similar to using $aAnimalNames[0]<br />
$aAnimalNames[$eDog] = 'Beethoven' ; $eDog is equal to 1, similar to using $aAnimalNames[1]<br />
$aAnimalNames[$eMouse] = 'Pinky' ; $eMouse is equal to 2, similar to using $aAnimalNames[2]<br />
$aAnimalNames[$eHamster] = 'Fidget' ; $eHamster is equal to 3, similar to using $aAnimalNames[3]<br />
<br />
; Display the values of the array.<br />
MsgBox($MB_SYSTEMMODAL, '', '$aAnimalNames[$eCat] = ' & $aAnimalNames[$eCat] & @CRLF & _<br />
'$aAnimalNames[$eDog] = ' & $aAnimalNames[$eDog] & @CRLF & _<br />
'$aAnimalNames[$eMouse] = ' & $aAnimalNames[$eMouse] & @CRLF & _<br />
'$aAnimalNames[$eHamster] = ' & $aAnimalNames[$eHamster] & @CRLF)<br />
<br />
; 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<br />
; 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<br />
; it appears in the initial declaration e.g.<br />
<br />
; Local Enum $eDog, $eMouse, $eCat, $eHamster<br />
<br />
; 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<br />
; $aAnimalNames[2], as well as for the other elements which have now shifted.<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Au3Check directive ==<br />
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.<br />
<br />
With the official custom directive used to check the helpfile examples/includes, you can apply the good coding practices listed above:<br />
<syntaxhighlight lang="autoit"><br />
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7<br />
</syntaxhighlight><br />
<br />
<br />
<br />
<br />
== Magic Numbers ==<br />
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. <br />
<br />
For example:<br />
<syntaxhighlight lang="autoit"><br />
MsgBox(262144, "Magic Numbers", "It's Adventure Time!")<br />
</syntaxhighlight><br />
In this example, the magic number is 262144 with the identifier being $MB_TOPMOST according to the helpfile.<br />
<br />
<br />
Example 2:<br />
<syntaxhighlight lang="autoit"><br />
; 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?<br />
; Since AutoIt is relatively a new concept to you, your first thought isn't to search through all the include files, I mean<br />
; why would you, the help file is there for a reason.<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, 128) ; Does this hide, show or disable it?<br />
GUICtrlSetState(Default, 64) ; Does this hide, show or disable it?<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case -3 ; Doesn't really tell much about what it does.<br />
ExitLoop<br />
<br />
Case -4, -5 ; Again, no idea what these are. MouseMove? MouseClick? Restore?<br />
MsgBox(4096, '', 'Do something when this action takes place.')<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
Did you understand the numbers were these:<br />
<syntaxhighlight lang="autoit"><br />
#include <GUIConstantsEx.au3><br />
<br />
Example()<br />
<br />
Func Example()<br />
Local $hGUI = GUICreate('')<br />
GUICtrlCreateLabel('Why magic numbers are counter productive.', 5, 5)<br />
GUICtrlSetState(Default, $GUI_DISABLE) ; Better, this is documented in the help file.<br />
GUICtrlSetState(Default, $GUI_ENABLE) ; Better, this is documented in the help file.<br />
GUISetState(@SW_SHOW, $hGUI)<br />
<br />
While 1<br />
Switch GUIGetMsg()<br />
Case $GUI_EVENT_CLOSE ; Better, this is documented in the help file. Ah, it's the close action.<br />
ExitLoop<br />
<br />
Case $GUI_EVENT_MINIMIZE, $GUI_EVENT_RESTORE ; Better, this is documented in the help file.<br />
MsgBox($MB_SYSTEMMODAL, '', 'Do something when this action takes place.') ; Better, this is documented in the help file.<br />
<br />
EndSwitch<br />
WEnd<br />
<br />
GUIDelete($hGUI)<br />
EndFunc ;==>Example<br />
</syntaxhighlight><br />
<br />
[http://en.wikipedia.org/wiki/Magic_number_(programming) Magic number (programming)]<br />
<br />
<br />
<br />
<br />
== Include-once directive ==<br />
This one is designed for standard includes and UDFs, it's highly recommended to use it.<br />
<br />
Those includes may be included in more than one script of your project because they are needed for some includes or your script itself.<br />
In that case, the code will be duplicated which is not a good thing especially if you have (and it's mainly the case) constants declared in those files, in so far as the constants cannot be redeclared/reassigned; same thing for functions.<br />
<br />
<br />
Put the directive in top of your UDF (library) to avoid itself to be included more than once :<br />
<syntaxhighlight lang="autoit"><br />
#include-once<br />
</syntaxhighlight></div>Czardashttps://www.autoitscript.com/w/index.php?title=Talk:Best_coding_practices&diff=12852Talk:Best coding practices2015-03-06T08:47:50Z<p>Czardas: </p>
<hr />
<div>Have you ever seen this thread?<br />
http://www.autoitscript.com/forum/topic/152580-cant-click-2nd-div-object/#entry1095954<br />
<br />
I do not check this<br />
"using "==" instead of "=" for object's properties"<br />
<br />
Is it true that this way is better?<br />
<br />
If YES then this may be helpful as additional information to this Wiki Documents<br />
<br />
I'm wondering what the variable initialization column is about. I can only assume that these values are suggestions. The wording would indicate they are not merely so. Either I'm missing something or this needs to be ammended. It appears to me that variables are initialized as empty strings by default. czardas</div>Czardashttps://www.autoitscript.com/w/index.php?title=Talk:Best_coding_practices&diff=12851Talk:Best coding practices2015-03-06T08:42:50Z<p>Czardas: </p>
<hr />
<div>Have you ever seen this thread?<br />
http://www.autoitscript.com/forum/topic/152580-cant-click-2nd-div-object/#entry1095954<br />
<br />
I do not check this<br />
"using "==" instead of "=" for object's properties"<br />
<br />
Is it true that this way is better?<br />
<br />
If YES then this may be helpful as additional information to this Wiki Documents<br />
<br />
I'm wondering what the variable initialization column is about. I can only assume that these values are suggestions. The wording would indicate they are not merely so. Either I'm missing something or this needs to be ammended. It appears to me that variables are initialized as empty strings by default.</div>Czardashttps://www.autoitscript.com/w/index.php?title=User_Defined_Functions&diff=12775User Defined Functions2015-02-22T22:38:54Z<p>Czardas: </p>
<hr />
<div>This page is a listing of libraries of '''user defined functions''' (UDF). These libraries have been written to allow easy integration into your own scripts and are a very valuable resource for any programmer.<br />
This list is probably not complete, but constantly supplemented.<br />
If you do not find a solution here, ask a new question on the [http://www.autoitscript.com/forum/forum/2-general-help-and-support/ forum].<br />
<br />
== Automation ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=87956 Java UDF] - Creates an access bridge between your application and a Java application. Allowing you to automate some Java applications.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=86574 SAP] - SAP business management automation.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=149540 SAPWizard] - SAPWizard.UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=91018 WiFi] - Low level control over your wireless LAN <br />
* [http://www.autoitscript.com/forum/index.php?showtopic=106163 Active Directory] - Extensive library to control and manipulate the Windows active directory. Link to the [[Active_Directory_UDF_-_General|documentation]] pages. <br />
* [http://www.autoitscript.com/forum/index.php?showtopic=80201 Service] - Build your own service with AutoIt code.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=150231 GTK+ ] - GTK+ Framework | Widgets<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=153520 IUIAutomation MS framework] - IUIAutomation MS framework automate chrome, FF, IE, ....<br />
===Browsers===<br />
* Internet Explorer - Everything about Internet explorer can be automated with the IE library supplied with a standard AutoIt install.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=166542 HTMLDocumentEvents UDF] - Track IE document events<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=166304 IEJS UDF] - IEJS - IE Javascript options, an IE.au3 personal extension<br />
<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=95595 Firefox] - A little less support for automation than IE, but still very good.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=61090 Opera] - The same as above for Opera. Automate the most common tasks in Opera with the Opera UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=154439 Chrome] - The same as above for Google Chrome. Automate the most common tasks in Chrome with the Chrome UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=149203 NavInfo UDF] - With this UDF now you can check if a specified browser/software is installed an you are also able to get what version is in used..<br />
<br />
===Microsoft Office Automation===<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=32144 Microsoft Office Access] - Automation of Access.<br />
* Microsoft Office Excel - A way to automate Office Excel is included with AutoIt. Link to the [[Excel_UDF|documentation]] pages.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=135312 Microsoft Office Excel Charts] - Creating charts using Excel.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=126305 Microsoft Office Outlook] - Extended Outlook UDF. Link to the [[OutlookEX_UDF_-_General|documentation]] pages.<br />
* Microsoft Office Word UDF - A way to automate Office Word is included with AutoIt. Link to the [[Word_UDF|documentation]] pages.<br />
<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=34302 ExcelCOM UDF] Yet Another -- ExcelCOM UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=50254 PowerPoint Wrapper] It allows you to have control of MS PowerPoint.<br />
<br />
== Hardware ==<br />
* [[CommAPI]] - Serial and parallel communication (COM port, RS-232, LPT port) - without installing DLL's (using Windows API calls)<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=128546 Serial Port/COM] - Serial Port /COM Port UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=68866 Webcam UDF] - Webcam UDF made by LIMITER.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=70857 Webcam UDF] - Webcam UDF made by ludocus.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=27755 SMARTDRIVE] - SMART drive Analysis.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=97487 DirectShow] - DirectShow UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=154350 Monitor Configuration] - Monitor Configuration UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=20121 Screen Resolution] - Screen Resolution Changing UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=77731 Device Management] - Device Management API<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=155469 Mouse_UDF] - AutoIt powered mouse events<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=155539 Network configuration UDF] - Network configuration UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=138989 FritzBox] - _FB_Tools - manage your FritzBox from Autoit<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=147325 MouseTrapEvent] - MouseTrapEvent UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=149083 NetInfo UDF] - UDF for test internet download speed and upload speed.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=164700 DirectSound UDF] - DirectSound UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=164701 Direct2D UDF] - Direct2D UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=121084 I/O Port Functions UDF] - This is a simple I/O (Input/Output) UDF for interacting with ports. (I/O Port Functions - x64 Parallel Port IO, Keyboard, etc + Restore PC Speaker Beep)<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=15864 SPI Hardware Interface] - This script is made to comunicate with the MAX335 chip using the SPI protocol via the LPT(printer) port.<br />
<br />
== Information gathering ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=29404 Computer information] - A general purpose library to get various details about a Windows machine.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=54039 WinPCap - Packet.dll UDF] - <br />
* [http://opensource.grisambre.net/pcapau3/#reference WinPcap Autoit3 UDF] - This UDF allows very simply from an Autoit script to access the main functionalities offered by the WinPcap driver.<br />
<br />
== Databases and web connections ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=17099 SQLite] - "SQLite is a library that implements a self-contained, embeddable, zero-configuration SQL database engine"<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=19848 XML DOM Wrapper] - Supports CRUD operations on XML. Including XSL and XPath.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=20814 MySQL] - MySQL relational database management system UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=85617 MySQL] - MySQL UDFs (without ODBC).<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=145142 DBF] - dBase database read and write with DLL.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=116072 EzMySql] - EzMySql UDF - Use MySql Databases with autoit.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=127101 MS SQL] - MSSQL.au3<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=51952 MS SQL] - _SQL.au3. ADODB.Connection<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=105875 ADODB] - ADODB Example<br />
* [http://www.autoitscript.com/forum/topic/94920-solved-passing-parameters-using-dllcall-to-a-c-dll/#entry684751 FireBird UDF] - FireBird, Interbase dll udf.<br />
* [http://stackoverflow.com/questions/21991475/autoit-firebird-sql-combo-return-data-as-csv-instead-of-xml FireBird UDF] - additional link to FireBird UDF<br />
<br />
== Internet protocol suite ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=84133 WinHTTP] - Enables scripts to access the HTTP protocol for creating GET and POST requests and submitting them with conforming standards, cookies not supported.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=77503 WinInet] - Enables scripts to access standard Internet protocols, such as FTP, Gopher and HTTP. Also supports creating GET and POST requests and submitting them with conforming standards, cookies supported.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=22838 POP3] - POP3 library for retrieving email messages. Not compatible with Gmail because it uses SSL.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=167339 _POP3_Ex.au3 UDF] POP3 UDF According to the 1939 RFC, modified version with Quoted Printable decoder.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=64051 POP3 SSL] - A POP3 library that's compatible with Gmail. It uses an external executable that must be supplied with your script.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=43515 IRC] - A lightweight library for communicating with IRC servers.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=138095 SFTP] - UDF to support SFTP protocol using PSFTP.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=104150 JSON] - RFC4627 compliant JSON encode/decode<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=148114 JSON] - JSMN - A Non-Strict JSON UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=156794 JSON] - Bridge to Native Windows JSON plus OO extension for AutoIt<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=137456 cURL] - cURL UDF - a UDF for transferring data with URL syntax<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=81687 SNMP UDF] - SNMP_UDF for SNMPv1 and SNMPv2c<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=70759 SNMP - MIB protocol] (Reading toner status from SNMP device with WMI).<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=43515 IRC] IRC UDF made by Chip<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=159285 IRC] IRC UDF - Updated Version of Chips' IRC UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=57022 UPnP Protocol] - UPnP : Read and Control your devices in side out.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=154530 Prowl] - Prowl UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=40243 IMAP] - IMAP.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=108422 IMAP4 UDF] - IMAP4 UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=166579 SSH UDF] - This UDF allows to use the SSH protocol very easily in your code.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=23860 SMTP] - Smtp Mailer That Supports Html And Attachments.<br />
<br />
== Data compression ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=116565 zip] - Create ZIP files and unpack ZIP files.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=85094 7z, zip, gzip, bzip2, tar] - More extensive library than the one above. Uses a external DLL that must be provided with the script.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=161847 XZip] - UDF for "XStandard XZIP Component".<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=17727 XZip] - another UDF for "XStandard XZIP Component".<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=73425 ZIP] - ZIP.au3 UDF in pure AutoIt.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=76176 UnRAR] - UnRAR.au3.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=128962 zLib] - zLib (Deflate/Inflate/GZIP) UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=135565 ZIP] - ZIP STRUCTS UDF (from scratch)<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=129529 pZip] - PureZIP_L library UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=44524 Zip plugin] - Zip plugin<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=112273 LZMA Compression UDF] - LZMA Compression UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=87441 LZMA] - LZMA (Native Windows) by trancexx<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=138838 Package UDF] - Package UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=166634 MessagePack UDF] - MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. But it's faster and smaller.<br />
<br />
== Encryption and hash ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=76976 MD5,SHA1,CRC32,RC4,BASE64,XXTEA] - Several encryption and hash functions.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=78745 AES Rijndael] - Very fast AES UDF. Support ECB/CBC/CFB/OFB block cipher mode.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=107784 TrueCrypt] - TrueCrypt UDFs.<br />
<br />
== Media ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=94834 Simple DirectMedia Layer UDF] - Adds support for joysticks, CDs, 2D graphics, timers. See [http://www.libsdl.org/ SDL website] for more information.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=95357 FreeImage library] - Various operations on images, such as rotate, resize, flip.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=51054 Printer controller] - Print text in any font, size and colour at any position on the page, draw lines, curves, elipses, pies in any colour, and print images.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=73993 Printing] - Printing from AutoIt.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=161831 RTF_Printer] - RTF_Printer.au3 - Printing RichEdit in the background.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=89542 OCR] - Tesseract (Screen OCR) UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=89542 Real OCR] - Real OCR in AU3 - MODI with MS Office 2003.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=127263 HtmlHelp UDF] - HtmlHelp UDF<br />
===Sound===<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=83481 BASS Function Library] - Sound and Music via wrappers for Bass, BassEnc, Bass FX, BassSFX, BassAsio and BassCd DLLs<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=100439 TTS] - Text-to-Speech UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=37072 MIDI] - MIDI UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=114742 SAPIListBox UDF] - SAPIListBox (Speech Recognition) UDF<br />
<br />
===Graphics and image===<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=70506 IrrLicht] - A 3D graphics engine suitable for creating games.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=113881 au3Irrlicht2] - Another UDF bringing Irrlicht and au3 together. Historically some kind of a follower of the UDF above, technically with a complete different approach.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=27362 Bitmap Library] - Bitmap Library.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=151011 OpenGL UDF] - OpenGL without external libraries<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=13096 ImageGetInfo] - This is an UDF for reading info from JPEG, TIFF, BMP, PNG and GIF - size, color depth, resolution etc. For JPEG files UDF also retreive various Exif information.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=148129 OpenGL UDFs (2.0)] - new set of UDFs for OpenGL + AutoIt<br />
<br />
===Players===<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=114143 VLC UDF] - VLC (Media Player) UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=91316 VLC Media Player] - VLC Media Player<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=27352 WMP UDF] - Windows Media Player UDF<br />
<br />
== GUI Additions ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=32494 XSkin] - A large library that allows skinning of your GUI and to apply custom skins.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=132864 Uskin] - A library that allows a user to skin their application GUI using the Windows ''.MSstyles'' files.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=20967 Modern tray menu] - Allows the creation of modern, fancy GUI and tray menus with icons and colors.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=71811 SetOnEvent] - Provides an easy way for an event to call functions with parameters.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=119505 GUIFrame] - Divide a GUI into adjustable frames.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=113723 Easy Scrollbars] - Easily create scrollable sections in your GUI<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=105582 GUICtrlOnChangeRegister] - Call a function when an edits content is changed.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=96258 ContextHelp.au3] - Management of context help ([http://www.autoitscript.com/forum/index.php?showtopic=72152-contexthelp/ original])<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=145149 GUIExtender] - Expand and contract sections of your GUI. ([http://www.autoitscript.com/forum/index.php?showtopic=117909 original])<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=109096 ExtMsgBox] - A very customisable replacement for MsgBox<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=108445 Toast] - Small message GUIs which pop out of the Systray<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=144207 GUI Panel UDF] - Manage child GUIs as panel ctrls<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=161750 Pie chart] - Pie chart<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=97241 3D Pie chart] - 3D Pie chart<br />
<br />
=== Controls ===<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=79412 Graph control UDF] - Easily create and show bar chart and line charts.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=105682 GUICtrlCreateFinder] - Allows you to create a window finder control like the one seen in AutoIt Window Info.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=111438 GUIPager] - Create and control native pager controls.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=90598 Hotkey input control] - Hotkeys Input Control UDF Library (Non-native)<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=107965 GUIHotkey] - UDF for using native hotkey controls.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=103904&p=735769 Marquees] - Make tickertape info bars<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=96464 Colorpicker] - Create a button for the user to select a color.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=126958 Syslink] - Provides a convenient way to embed hypertext links in a window<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=74649 Progressbar with GDIplus] - You even can use full textured images<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=105814 Table UDF] - Table UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=20967 Table UDF] - GUI/Tray Menu with icons and colors<br />
* [http://www.autoitscript.com/forum/topic/20967-guitray-menu-with-icons-and-colors/page-15#entry1205045 Table UDF] - GUI/Tray Menu with icons and colors (modified by LarsJ with extra examples by LarsJ and AZJIO)<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=128242 Ribbon] - UDF for Windows Ribbon framework.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=166594 GUITreeViewEx] - Check/clear parent and child checkboxes in a TreeView<br />
<br />
== Maths ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=83091 Primes UDF] - Many functions dealing with prime number generation and calculations.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=83529 Big number UDF] - Make calculations with extremely large numbers that AutoIt normally is not able to support.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=81189 Number base conversion] - From, to and between positive bases less than 63 (decimals supported)<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=106551 Decimal To fraction] - Converts any decimal number to a fraction. Example: 1.2 to 6/5<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=82722 Trigonometry math functions] - _ATan2(), _Cosh(), _Frexp(), _Hypot(), _Ldexp(), _Logb(), _Sinh(), _Tanh()<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=108803 Polynomials] - Functions for using polynomials.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=117156 NumToWord] - Convert numerals to a human readable string.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=98160 Root function] - Working out real roots of numbers.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=102686 Advanced rounding] - Support for different measures of accuracy and 8 ways to resolve tie breaks.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=94770 Roman Numerals] - integer to roman numerals made by Mat.<br />
* [http://www.autoitscript.com/forum/topic/123398-snippet-dump/page-3#entry1005157 Roman Numerals] - Roman Numerals made by czardas.<br />
* [http://www.autoitscript.com/forum/topic/94770-integer-to-roman-numerals/#entry1043544 Roman Numerals] - Roman Numerals made by AZJIO.<br />
<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=163899 StringAPL UDF] - inline APL interpreter.<br />
<br />
== Misc ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=90492 Hotkey.au3] - Management of Hotkeys UDF, with several advantages over HotkeySet().<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=97826 Animated tray icons] - Make animated tray icons easily.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=101733 NoFocusLines] - Remove the dotted focus lines from buttons, sliders, radios and checkboxes which spoil the look of your GUI<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=114034 StringSize] - Automatically size controls to fit the text you want to put in them<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=162033 Spell Checker] - Spell Checker UDF - Hunspell<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=125251 TVExplorer] - TVExplorer UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=162366 BinaryCall] - BinaryCall UDF - Write Subroutines In C, Call In AutoIt<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=161628 LFN] - LFN UDF - overcome MAX_PATH limit of 256 chars<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=81267 Clipboard History/Sotrage] - UDF to save and restore the entire clipboard contents<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=51103 Resources UDF] - Resources UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=162499 ResourcesEx UDF] - ResourcesEx UDF (up to date with the current AutoIt language syntax v3.3.12.0)<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=149176 NotifyIcon UDF] - NotifyIcon UDF (formerly TrayIconEx) - Create, delete and manage self notify icons<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=131037 Binary UDF] - Binary UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=99106 _DLLStructDisplay] - Show Struct in ListView<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=55994 DDEML UDF] - With DDEML UDF one can use an AutoIt script as a DDE client or server.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=157689 _FileGetMimeType UDF] - _FileGetMimeType UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=157241 FindMimeFromData] - FindMimeFromData using urlmon.dll<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=63318 PixelGetColor UDF] - Get or Read Pixel from Memory UDF<br />
* [http://www.autoitscript.com/forum/topic/117033-file-locking-with-cooperative-semaphores File locking with cooperative semaphores] - Simple file locking without a server<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=142977 SQLite Array Functions] - SQLite Array Functions - a faster method for unique arrays and sorting methods<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=164444 Synology filestation UDF] - UDF for users of Synology NAS server.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=163577 Atom Table UDF] - Basically, a bunch of strings can be stored locally (at program level) or globally (at O/S level) with unique numerical identifiers. This UDF lets you add, find, delete, and query these atoms.<br />
<br />
== PDF ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=42776 PDFCreator] - Automation of PDFCreator allows you to create and manipulate PDF files.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=160875 Debenu Quick PDF Library] - A collection of functions for Debenu Quick PDF Library.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=118827 MPDF] - Create PDF from your application.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=164469 Debenu PDF Viewer SDK - UDF] - A collection of functions to display PDF files in your applications using Debenu PDF Viewer SDK.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=75832 FoxIt Reader UDF] - PDF Reader in AU3.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=32261 _StringToPDF UDF] - Write a string to a PDF file and specify font size, type etc.<br />
<br />
== Windows ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=145158 Firewall] - Windows Firewall UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=158377 UAC] - User Account Control (UAC) UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=50880 ACL] - Set ACL on windows Objects.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=124508 Startup] - Create Startup entries in the Startup Folder or Registry<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=74118 Local account UDF] - Local account UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=81880 Windows Services UDF] - Windows Services UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=111018 ITaskBarList UDF] - ITaskBarList UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=113560 FileSystemMonitor UDF] - FileSystemMonitor UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=161193 Magnifier Functions UDF] - Magnifier Functions - Windows Vista+ Magnifier Manipulation<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=163178 WRMF UDF] - WRMF - Windows Registry Monitor Call Function<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=75250 Registry UDFs] - Windows Registry UDFs<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=50551 Registry] - RegWriteAllUsers / RegDeleteAllUsers<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=134628 System restore UDF] - System restore UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=83355 Task Sheduler] - Task Scheduler UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=135994 Taskplaner/Taskscheduler COM UDF] - an UDF for using the Windows Taskplaner / Task Scheduler<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=28436 Windows Events] - Create your own Windows events.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=161193 Magnifier Functions UDF] - This UDF exposes most of the useful Magnifier API functions available since Windows Vista.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=127075 WIMGAPI UDF] - A UDF for manipulating Windows Image Files (.wim) without ImageX.exe<br />
<br />
== Security ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=150819 VirusTotal] - VirusTotal API 2.0 UDF.<br />
[[Category:UDF]]<br />
<br />
== Social Media and other Website API ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=116600 Twitter] - Twitter UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=70675 iTunes] - iTunes UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=101802 iTunes] - another iTunes UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=149247 Yahoo Weather] - YWeather UDF - Yahoo Weather API.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=115437 Google Maps] - Google Maps UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=150473 Google API] - JSON queries for Google API.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=131343 PasteBin] - PasteBin (powered by PasteBin).<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=150838 PasteBin] - Pastebin UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=114801 eBay UDF] - eBay UDF.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=141340 Gmail] - Remote Gmail (UDF)<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=150985 No-IP UDF] - With this UDF you can simply update your no-ip hostname(s) and retrive the ip address of an no-ip address.<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=112775 Youtube Uploader] - AYTU - AutoIt Youtube Uploader<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=98504 Google Functions] - Google Functions<br />
* [http://www.autoitscript.com/forum/files/file/290-dropbox-authenticator/ Dropbox authenticator] - Dropbox authenticator<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=166547 TVmaze.com API UDF] - TVmaze.com API UDF (TV-Series)<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=113234 Teamspeak 3 UDF] - Teamspeak 3 UDF<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=166205 TeamViewer API - UDF] - UDF for TeamViewer API - a modest beginning<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=158106 Easypost UDF] - Print USPS Postage Labels<br />
<br />
== Android ==<br />
* [http://www.autoitscript.com/forum/index.php?showtopic=160936 Android UDF] - Android UDF.</div>Czardashttps://www.autoitscript.com/w/index.php?title=Snippets_(_AutoIt_String_)&diff=11631Snippets ( AutoIt String )2013-04-18T20:32:44Z<p>Czardas: /* _StringEqualSplit */</p>
<hr />
<div>__TOC__<br />
<br />
[[category:Snippets]]<br />
<br />
{{Snippet Credit Header}}<br />
<br />
== _StringEqualSplit ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 15769-czardas<br />
| AuthorName = czardas<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
Local $aArray = _StringEqualSplit("12345678910", 3)<br />
_ArrayDisplay($aArray)<br />
<br />
Func _StringEqualSplit($sString, $iNumChars)<br />
If Not IsString($sString) Or $sString = "" Then Return SetError(1, 0, 0)<br />
If Not IsInt($iNumChars) Or $iNumChars < 1 Then Return SetError(2, 0, 0)<br />
Return StringRegExp($sString, "(?s).{1," & $iNumChars & "}", 3)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringGetChrCount ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 52-geosoft<br />
| AuthorName = GEOSoft<br />
| Desc = Check how many times the word 'test' appears in the string. 1 = Case-sensitive or 0 = Non Case-sensitive.<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
; Check how many times the word 'test' appears in the string. 1 = Case-sensitive or 0 = Non Case-sensitive.<br />
ConsoleWrite(_StringGetChrCount("test teste test", "TEST", 0) & @CRLF)<br />
<br />
Func _StringGetChrCount($sStr, $sChr, $iCase = 0)<br />
If $iCase <> 0 Then<br />
$iCase = 1<br />
EndIf<br />
StringReplace($sStr, $sChr, $sChr, 0, $iCase)<br />
Return @extended<br />
EndFunc ;==>_StringGetChrCount<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringEqualSplit ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 15769-czardas<br />
| AuthorName = czardas<br />
| ModifierURL = 35302-guinness<br />
| ModifierName = guinness<br />
| Desc = Splits a string into an equal number of characters. The 0th index returns the number of items.<br />
}}<br />
<br />
<syntaxhighlight lang="autoit">#include <Array.au3><br />
#include <String.au3><br />
<br />
Local $aSplitEqual = _StringEqualSplit('abcdefghijklmnopqrstuvwxyz', 5)<br />
_ArrayDisplay($aSplitEqual)<br />
<br />
; By czardas & modified by guinness >> http://www.autoitscript.com/forum/topic/139260-autoit-snippets/page__st__20#entry992149<br />
; Version: 1.10. AutoIt: V3.3.8.1<br />
; Splits a string into an equal number of characters. The 0th index returns the number of items.<br />
Func _StringEqualSplit($sString, $iNumChars)<br />
If IsString($sString) = 0 Or $sString == '' Then<br />
Return SetError(1, 0, 0)<br />
EndIf<br />
<br />
If IsInt($iNumChars) = 0 Or $iNumChars < 1 Then<br />
Return SetError(2, 0, 0)<br />
EndIf<br />
<br />
Local $aReturn = StringRegExp(_StringRepeat('0', 5) & $sString, '(?s).{1,' & $iNumChars & '}', 3)<br />
$aReturn[0] = UBound($aReturn, 1) - 1<br />
Return $aReturn<br />
EndFunc ;==>_StringEqualSplit</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringIsNum ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 38301-smartee<br />
| AuthorName = smartee<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
ConsoleWrite(StringIsNum('Example') & @CRLF)<br />
ConsoleWrite(StringIsNum('123456') & @CRLF)<br />
ConsoleWrite(StringIsNum('Example & 123456') & @CRLF)<br />
<br />
Func StringIsNum($sString)<br />
Return StringRegExp($sString, "^([0-9]*(\.[0-9]+){1}|[0-9]+(\.[0-9]*){0,1})$") = 1<br />
EndFunc ;==>StringIsNum<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringRemoveLine ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 4813-smoke-n<br />
| AuthorName = SmOke_N<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
Global $string = 'This is an example' & @CRLF & 'Of deleting a line' & @CRLF & 'If you know at least the beginning text of the line.'<br />
<br />
MsgBox(0, 'Original', $string)<br />
<br />
Global $deleteline = _StringRemoveLine($string, 'Of deleting')<br />
<br />
MsgBox(0, 'Deleted Line', $deleteline)<br />
<br />
Func _StringRemoveLine($hFile, $sDelete)<br />
If FileExists($hFile) Then $hFile = FileRead($hFile);Remove If FileExists($hFile) Then << only<br />
Local $nSNS = StringInStr($hFile, @CRLF & $sDelete) - 1<br />
Local $sSFH = StringLeft($hFile, $nSNS)<br />
Local $sRL = StringTrimLeft($hFile, StringLen($sSFH) + 2)<br />
Local $sLLEN = StringLen(StringLeft($sRL, StringInStr($sRL, @CRLF)))<br />
If Not $sLLEN Then $sLLEN = StringLen($sRL)<br />
Return $sSFH & StringTrimLeft($hFile, $sLLEN + $nSNS + 2)<br />
EndFunc ;==>_StringRemoveLine()<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringReplaceBlank ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 4813-smoke-n<br />
| AuthorName = SmOke_N<br />
| Desc = Remove blank lines from a File<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
; Remove blank lines from a File<br />
Local $sString = "I am a string" & @CRLF & @CRLF & _<br />
"With Empty Lines" & @CRLF & @CRLF & _<br />
"Please Remove those empty lines"<br />
<br />
MsgBox(4096, "Before", $sString)<br />
<br />
$sString = _StringReplaceBlank($sString, 1)<br />
<br />
MsgBox(4096, "Replaced: " & @extended & " lines.", $sString)<br />
<br />
Func _StringReplaceBlank($sString, $sSpaces = "")<br />
If $sSpaces Then<br />
$sSpaces = "\s*"<br />
EndIf<br />
<br />
$sString = StringRegExpReplace($sString, "(?s)\r\n" & $sSpaces & "\r\n", @CRLF)<br />
<br />
If @extended Then<br />
Return SetError(0, @extended, $sString)<br />
EndIf<br />
<br />
Return SetError(1, 0, $sString)<br />
EndFunc ;==>_StringReplaceBlank<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringTrimLeftIsEqual ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 35302-guinness<br />
| AuthorName = guinness<br />
| Desc = Strip a character/word from the leftmost part of a string.<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
ConsoleWrite(_StringTrimLeftIsEqual('C:\Test', 'C:\') & @CRLF) ; Returns Test as the string 'C:\' is stripped from the left.<br />
ConsoleWrite(_StringTrimLeftIsEqual('C:\Test\', 'C') & @CRLF) ; Returns :\Test as the character 'C' is stripped from the left.<br />
ConsoleWrite(_StringTrimLeftIsEqual('C:\Test\', 'Test') & @CRLF) ; Returns the initial string as the string 'Test' was not found to the leftmost part of the string.<br />
<br />
; Version: 1.00. AutoIt: V3.3.8.1<br />
; Strip a character/word from the leftmost part of a string.<br />
Func _StringTrimLeftIsEqual($sString, $sStringTrim)<br />
Local $aStringTrim[2] = [0, StringLen($sStringTrim)]<br />
Return StringTrimLeft($sString, $aStringTrim[Number(StringLeft($sString, $aStringTrim[1]) == $sStringTrim)])<br />
EndFunc ;==>_StringTrimLeftIsEqual<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringTrimRightIsEqual ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 35302-guinness<br />
| AuthorName = guinness<br />
| Desc = Strip a character/word from the rightmost part of a string.<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
ConsoleWrite(_StringTrimRightIsEqual('C:\Test', 'Test') & @CRLF) ; Returns C:\ as the string 'Test' is stripped from the right.<br />
ConsoleWrite(_StringTrimRightIsEqual('C:\Test\', '\') & @CRLF) ; Returns C:\Test as the character '\' is stripped from the right.<br />
ConsoleWrite(_StringTrimRightIsEqual('C:\Test\', 'Test') & @CRLF) ; Returns the initial string as the string 'Test' was not found to the rightmost part of the string.<br />
<br />
; Version: 1.00. AutoIt: V3.3.8.1<br />
; Strip a character/word from the rightmost part of a string.<br />
Func _StringTrimRightIsEqual($sString, $sStringTrim)<br />
Local $aStringTrim[2] = [0, StringLen($sStringTrim)]<br />
Return StringTrimRight($sString, $aStringTrim[Number(StringRight($sString, $aStringTrim[1]) == $sStringTrim)])<br />
EndFunc ;==>_StringTrimRightIsEqual<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringRegExpSplit ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 69238-dany<br />
| AuthorName = dany<br />
| Desc = Split a string based on a regular expression.<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
; Split a string based on a regular expression.<br />
; http://www.autoitscript.com/forum/topic/139260-autoit-snippets/page__st__120#entry1036533<br />
#include <Array.au3> ; Only needed for example.<br />
Global $sString = 'List:' & _<br />
'1. Bananas' & _<br />
'2. Coconuts' & _<br />
'3. Apples'<br />
_ArrayDisplay(_StringRegExpSplit($sString, '[0-9]+\. ?')) ; Use the numbering (#.) to split on.<br />
Global $bBinary = Binary($sString)<br />
_ArrayDisplay(_StringRegExpSplit($bBinary, '3[0-9]2E(20)?'))<br />
<br />
; #FUNCTION# ===================================================================<br />
; Name...........: _StringRegExpSplit<br />
; Description ...: Split a string according to a regular expression.<br />
; Syntax.........: _StringRegExpSplit($sString, $sPattern)<br />
; Parameters ....: $sString - String: String to split.<br />
; $sPattern - String: Regular expression to split on.<br />
; Return values .: Success - Array: Array of substrings, the total is in $array[0].<br />
; Failure - Array: The count is 1 ($array[0]) and the full string is returned ($array[1]) and sets @error:<br />
; |1 Delimiter not found.<br />
; |2 Bad RegExp pattern, @extended contains the offset of the error in the pattern.<br />
; |3 No suitable placeholder delimiter could be constructed.<br />
; Author ........: dany<br />
; Modified ......: czardas, AZJIO<br />
; Remarks .......:<br />
; Related .......:<br />
; ==============================================================================<br />
Func _StringRegExpSplit($sString, $sPattern)<br />
Local $sSplit, $sDelim, $aError[2] = [1, $sString]<br />
For $i = 1 To 31<br />
$sDelim &= Chr($i)<br />
If Not StringInStr($sString, $sDelim) Then ExitLoop<br />
If 32 = StringLen($sDelim) Then Return SetError(3, 0, $aError)<br />
Next<br />
$sSplit = StringRegExpReplace($sString, $sPattern, $sDelim)<br />
If @error Then Return SetError(2, @extended, $aError)<br />
If @extended = 0 Then Return SetError(1, 0, $aError)<br />
If Not IsBinary($sString) Then Return StringSplit($sSplit, $sDelim, 1)<br />
$sSplit = StringSplit($sSplit, $sDelim, 1)<br />
For $i = 2 To $sSplit[0]<br />
$sSplit[$i] = '0x' & $sSplit[$i]<br />
Next<br />
Return $sSplit<br />
EndFunc ;==>_StringRegExpSplit<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]</div>Czardashttps://www.autoitscript.com/w/index.php?title=Snippets_(_AutoIt_String_)&diff=11630Snippets ( AutoIt String )2013-04-18T19:30:36Z<p>Czardas: /* _StringEqualSplit */</p>
<hr />
<div>__TOC__<br />
<br />
[[category:Snippets]]<br />
<br />
{{Snippet Credit Header}}<br />
<br />
== _StringEqualSplit ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 15769-czardas<br />
| AuthorName = czardas<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <Array.au3><br />
Global $aArray = _StringEqualSplit("abcdefghijklmnopqrstuvwxyz", 5)<br />
_ArrayDisplay($aArray)<br />
<br />
Func _StringEqualSplit($sString, $iNumChars)<br />
If Not IsString($sString) Or $sString = "" Then Return SetError(1, 0, 0)<br />
If Not IsInt($iNumChars) Or $iNumChars < 1 Then Return SetError(2, 0, 0)<br />
Return StringRegExp($sString, "(?s).{1," & $iNumChars & "}", 3)<br />
EndFunc<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringGetChrCount ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 52-geosoft<br />
| AuthorName = GEOSoft<br />
| Desc = Check how many times the word 'test' appears in the string. 1 = Case-sensitive or 0 = Non Case-sensitive.<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
; Check how many times the word 'test' appears in the string. 1 = Case-sensitive or 0 = Non Case-sensitive.<br />
ConsoleWrite(_StringGetChrCount("test teste test", "TEST", 0) & @CRLF)<br />
<br />
Func _StringGetChrCount($sStr, $sChr, $iCase = 0)<br />
If $iCase <> 0 Then<br />
$iCase = 1<br />
EndIf<br />
StringReplace($sStr, $sChr, $sChr, 0, $iCase)<br />
Return @extended<br />
EndFunc ;==>_StringGetChrCount<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringEqualSplit ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 15769-czardas<br />
| AuthorName = czardas<br />
| ModifierURL = 35302-guinness<br />
| ModifierName = guinness<br />
| Desc = Splits a string into an equal number of characters. The 0th index returns the number of items.<br />
}}<br />
<br />
<syntaxhighlight lang="autoit">#include <Array.au3><br />
#include <String.au3><br />
<br />
Local $aSplitEqual = _StringEqualSplit('abcdefghijklmnopqrstuvwxyz', 5)<br />
_ArrayDisplay($aSplitEqual)<br />
<br />
; By czardas & modified by guinness >> http://www.autoitscript.com/forum/topic/139260-autoit-snippets/page__st__20#entry992149<br />
; Version: 1.10. AutoIt: V3.3.8.1<br />
; Splits a string into an equal number of characters. The 0th index returns the number of items.<br />
Func _StringEqualSplit($sString, $iNumChars)<br />
If IsString($sString) = 0 Or $sString == '' Then<br />
Return SetError(1, 0, 0)<br />
EndIf<br />
<br />
If IsInt($iNumChars) = 0 Or $iNumChars < 1 Then<br />
Return SetError(2, 0, 0)<br />
EndIf<br />
<br />
Local $aReturn = StringRegExp(_StringRepeat('0', 5) & $sString, '(?s).{1,' & $iNumChars & '}', 3)<br />
$aReturn[0] = UBound($aReturn, 1) - 1<br />
Return $aReturn<br />
EndFunc ;==>_StringEqualSplit</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringIsNum ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 38301-smartee<br />
| AuthorName = smartee<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
ConsoleWrite(StringIsNum('Example') & @CRLF)<br />
ConsoleWrite(StringIsNum('123456') & @CRLF)<br />
ConsoleWrite(StringIsNum('Example & 123456') & @CRLF)<br />
<br />
Func StringIsNum($sString)<br />
Return StringRegExp($sString, "^([0-9]*(\.[0-9]+){1}|[0-9]+(\.[0-9]*){0,1})$") = 1<br />
EndFunc ;==>StringIsNum<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringRemoveLine ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 4813-smoke-n<br />
| AuthorName = SmOke_N<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
Global $string = 'This is an example' & @CRLF & 'Of deleting a line' & @CRLF & 'If you know at least the beginning text of the line.'<br />
<br />
MsgBox(0, 'Original', $string)<br />
<br />
Global $deleteline = _StringRemoveLine($string, 'Of deleting')<br />
<br />
MsgBox(0, 'Deleted Line', $deleteline)<br />
<br />
Func _StringRemoveLine($hFile, $sDelete)<br />
If FileExists($hFile) Then $hFile = FileRead($hFile);Remove If FileExists($hFile) Then << only<br />
Local $nSNS = StringInStr($hFile, @CRLF & $sDelete) - 1<br />
Local $sSFH = StringLeft($hFile, $nSNS)<br />
Local $sRL = StringTrimLeft($hFile, StringLen($sSFH) + 2)<br />
Local $sLLEN = StringLen(StringLeft($sRL, StringInStr($sRL, @CRLF)))<br />
If Not $sLLEN Then $sLLEN = StringLen($sRL)<br />
Return $sSFH & StringTrimLeft($hFile, $sLLEN + $nSNS + 2)<br />
EndFunc ;==>_StringRemoveLine()<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringReplaceBlank ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 4813-smoke-n<br />
| AuthorName = SmOke_N<br />
| Desc = Remove blank lines from a File<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
; Remove blank lines from a File<br />
Local $sString = "I am a string" & @CRLF & @CRLF & _<br />
"With Empty Lines" & @CRLF & @CRLF & _<br />
"Please Remove those empty lines"<br />
<br />
MsgBox(4096, "Before", $sString)<br />
<br />
$sString = _StringReplaceBlank($sString, 1)<br />
<br />
MsgBox(4096, "Replaced: " & @extended & " lines.", $sString)<br />
<br />
Func _StringReplaceBlank($sString, $sSpaces = "")<br />
If $sSpaces Then<br />
$sSpaces = "\s*"<br />
EndIf<br />
<br />
$sString = StringRegExpReplace($sString, "(?s)\r\n" & $sSpaces & "\r\n", @CRLF)<br />
<br />
If @extended Then<br />
Return SetError(0, @extended, $sString)<br />
EndIf<br />
<br />
Return SetError(1, 0, $sString)<br />
EndFunc ;==>_StringReplaceBlank<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringTrimLeftIsEqual ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 35302-guinness<br />
| AuthorName = guinness<br />
| Desc = Strip a character/word from the leftmost part of a string.<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
ConsoleWrite(_StringTrimLeftIsEqual('C:\Test', 'C:\') & @CRLF) ; Returns Test as the string 'C:\' is stripped from the left.<br />
ConsoleWrite(_StringTrimLeftIsEqual('C:\Test\', 'C') & @CRLF) ; Returns :\Test as the character 'C' is stripped from the left.<br />
ConsoleWrite(_StringTrimLeftIsEqual('C:\Test\', 'Test') & @CRLF) ; Returns the initial string as the string 'Test' was not found to the leftmost part of the string.<br />
<br />
; Version: 1.00. AutoIt: V3.3.8.1<br />
; Strip a character/word from the leftmost part of a string.<br />
Func _StringTrimLeftIsEqual($sString, $sStringTrim)<br />
Local $aStringTrim[2] = [0, StringLen($sStringTrim)]<br />
Return StringTrimLeft($sString, $aStringTrim[Number(StringLeft($sString, $aStringTrim[1]) == $sStringTrim)])<br />
EndFunc ;==>_StringTrimLeftIsEqual<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringTrimRightIsEqual ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 35302-guinness<br />
| AuthorName = guinness<br />
| Desc = Strip a character/word from the rightmost part of a string.<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
ConsoleWrite(_StringTrimRightIsEqual('C:\Test', 'Test') & @CRLF) ; Returns C:\ as the string 'Test' is stripped from the right.<br />
ConsoleWrite(_StringTrimRightIsEqual('C:\Test\', '\') & @CRLF) ; Returns C:\Test as the character '\' is stripped from the right.<br />
ConsoleWrite(_StringTrimRightIsEqual('C:\Test\', 'Test') & @CRLF) ; Returns the initial string as the string 'Test' was not found to the rightmost part of the string.<br />
<br />
; Version: 1.00. AutoIt: V3.3.8.1<br />
; Strip a character/word from the rightmost part of a string.<br />
Func _StringTrimRightIsEqual($sString, $sStringTrim)<br />
Local $aStringTrim[2] = [0, StringLen($sStringTrim)]<br />
Return StringTrimRight($sString, $aStringTrim[Number(StringRight($sString, $aStringTrim[1]) == $sStringTrim)])<br />
EndFunc ;==>_StringTrimRightIsEqual<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]<br />
<br />
== _StringRegExpSplit ==<br />
<br />
{{Snippet Header<br />
| AuthorURL = 69238-dany<br />
| AuthorName = dany<br />
| Desc = Split a string based on a regular expression.<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
; Split a string based on a regular expression.<br />
; http://www.autoitscript.com/forum/topic/139260-autoit-snippets/page__st__120#entry1036533<br />
#include <Array.au3> ; Only needed for example.<br />
Global $sString = 'List:' & _<br />
'1. Bananas' & _<br />
'2. Coconuts' & _<br />
'3. Apples'<br />
_ArrayDisplay(_StringRegExpSplit($sString, '[0-9]+\. ?')) ; Use the numbering (#.) to split on.<br />
Global $bBinary = Binary($sString)<br />
_ArrayDisplay(_StringRegExpSplit($bBinary, '3[0-9]2E(20)?'))<br />
<br />
; #FUNCTION# ===================================================================<br />
; Name...........: _StringRegExpSplit<br />
; Description ...: Split a string according to a regular expression.<br />
; Syntax.........: _StringRegExpSplit($sString, $sPattern)<br />
; Parameters ....: $sString - String: String to split.<br />
; $sPattern - String: Regular expression to split on.<br />
; Return values .: Success - Array: Array of substrings, the total is in $array[0].<br />
; Failure - Array: The count is 1 ($array[0]) and the full string is returned ($array[1]) and sets @error:<br />
; |1 Delimiter not found.<br />
; |2 Bad RegExp pattern, @extended contains the offset of the error in the pattern.<br />
; |3 No suitable placeholder delimiter could be constructed.<br />
; Author ........: dany<br />
; Modified ......: czardas, AZJIO<br />
; Remarks .......:<br />
; Related .......:<br />
; ==============================================================================<br />
Func _StringRegExpSplit($sString, $sPattern)<br />
Local $sSplit, $sDelim, $aError[2] = [1, $sString]<br />
For $i = 1 To 31<br />
$sDelim &= Chr($i)<br />
If Not StringInStr($sString, $sDelim) Then ExitLoop<br />
If 32 = StringLen($sDelim) Then Return SetError(3, 0, $aError)<br />
Next<br />
$sSplit = StringRegExpReplace($sString, $sPattern, $sDelim)<br />
If @error Then Return SetError(2, @extended, $aError)<br />
If @extended = 0 Then Return SetError(1, 0, $aError)<br />
If Not IsBinary($sString) Then Return StringSplit($sSplit, $sDelim, 1)<br />
$sSplit = StringSplit($sSplit, $sDelim, 1)<br />
For $i = 2 To $sSplit[0]<br />
$sSplit[$i] = '0x' & $sSplit[$i]<br />
Next<br />
Return $sSplit<br />
EndFunc ;==>_StringRegExpSplit<br />
</syntaxhighlight><br />
<br />
[[#top | Return To Contents]]</div>Czardashttps://www.autoitscript.com/w/index.php?title=AutoIt_Snippets&diff=11460AutoIt Snippets2012-11-19T11:22:24Z<p>Czardas: removed one word.</p>
<hr />
<div>Welcome To The AutoIt Snippets Page - ( '''''Snippet - A short reusable piece of computer code''''' ). <br />
<br />
Snippets are generally single functions or small pieces of code which can be incorporated into a script to add extra functionality. This section covers a wide variety of subjects and uses. Examples may include anything from finding if an internet connection is working to retrieving the date Windows was installed. This page is intended to give easy access to the functions.<br />
<br />
__TOC__<br />
<br />
[[category:Snippets]]<br />
<br />
{{Snippet Credit Header}}<br />
<br />
== Examples ==<br />
<br />
=== _IsInternetConnected ===<br />
<br />
{{Snippet Header<br />
| AuthorURL=35302-guinness<br />
| AuthorName=guinness<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
ConsoleWrite("Internet Is Connected" & " = " & _IsInternetConnected() & @CRLF) ; ( Returns "True" Or "False" )<br />
<br />
Func _IsInternetConnected()<br />
Local $aReturn = DllCall('connect.dll', 'long', 'IsInternetConnected')<br />
If @error Then<br />
Return SetError(1, 0, False)<br />
EndIf<br />
Return $aReturn[0] = 0<br />
EndFunc ;==>_IsInternetConnected<br />
</syntaxhighlight><br />
<br />
[[#top | ReturnToContents]]<br />
<br />
=== _PasswordCrypt ===<br />
<br />
{{Snippet Header<br />
| AuthorURL=4920-valuater<br />
| AuthorName=Valuater<br />
| ModifierURL=35302-guinness<br />
| ModifierName=guinness<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <Crypt.au3><br />
<br />
Local $sGenericPassword_1 = 'Password@AutoIt', $sGenericPassword_2 = 'NewPassword@AutoIt', $sSavePath = @ScriptDir & '\License.dat'<br />
ConsoleWrite('1. ' & _PasswordCrypt($sGenericPassword_1, $sSavePath) & @CRLF) ; Write the password to a file located in the @ScriptDir. The password we wrote is returned by the function.<br />
ConsoleWrite('2. ' & _PasswordCrypt($sGenericPassword_1, $sSavePath) & @CRLF) ; Since the password has been written already, we now want to check if the user has entered the password correctly. Returns True or False.<br />
ConsoleWrite('3. ' & _PasswordCrypt($sGenericPassword_2, $sSavePath, 1) & @CRLF) ; Overwrite the old password with a new one.<br />
ConsoleWrite('4. ' & _PasswordCrypt($sGenericPassword_1, $sSavePath) & @CRLF) ; Check the password matches. This will fail as we're checking the old password against the new one.<br />
FileDelete($sSavePath)<br />
<br />
Func _PasswordCrypt($sPassword, $sFilePath, $iOverwrite = 0) ; By guinness, idea by Valuater.<br />
If FileExists($sFilePath) And $iOverwrite = 0 Then<br />
Return BinaryToString(_Crypt_DecryptData(IniRead($sFilePath, 'PasswordKey', 'Password', ''), @ComputerName, $CALG_AES_256)) == $sPassword<br />
Else<br />
If IniWrite($sFilePath, 'PasswordKey', 'Password', _Crypt_EncryptData($sPassword, @ComputerName, $CALG_AES_256)) Then<br />
Return $sPassword<br />
EndIf<br />
EndIf<br />
Return SetError(1, 0, '')<br />
EndFunc ;==>_PasswordCrypt<br />
</syntaxhighlight><br />
<br />
[[#top | ReturnToContents]]<br />
<br />
== Snippet Creation Help ==<br />
<br />
* [[Snippets ( Creation )| Snippets Creation Examples ]]<br />
<br />
== AutoIt Snippets Collection ==<br />
<br />
=== AutoIt <small>- AutoIt Examples.</small> ===<br />
<br />
* [[Snippets ( AutoIt Audio )| Audio Related ]] ( Last Updated - 16:58, 21 May 2012 (BST) )<br />
* [[Snippets ( AutoIt )| AutoIt Miscellaneous ]] ( Last Updated - 12:22, 1 August 2012 (BST) )<br />
* [[Snippets ( AutoIt Array )| AutoIt Array Related]] ( Last Updated - 13:17, 21 May 2012 (BST) )<br />
* [[Snippets ( AutoIt Mouse & Keyboard )| AutoIt Mouse & Keyboard ]] ( Last Updated - 07:52, 3 August 2012 (BST) )<br />
* [[Snippets ( AutoIt String )| AutoIt String Related ]] ( Last Updated - 12:45, 1 August 2012 (BST) )<br />
<br />
=== GUI <small>- Anything GUI related.</small> ===<br />
<br />
* [[Snippets ( Checkboxes )| Checkboxes & Radio ]]<br />
* [[Snippets ( GUI )| GUI ]] ( Last Updated - 12:11, 1 August 2012 (BST) )<br />
* [[Snippets ( Graphics )| Graphics And Images ]] ( Last Updated - 12:37, 1 August 2012 (BST) )<br />
<br />
=== Hardware <small>- Hardware Examples.</small> ===<br />
<br />
* [[Snippets ( Hardware Information )| Hardware Information ]] ( Last Updated - 11:02, 30 April 2012 (BST) )<br />
<br />
=== Numbers <small>- Math, Number & Time Examples.</small> ===<br />
<br />
* [[Snippets ( Math & Numbers )| Math & Numbers ]] ( Last Updated - 12:07, 1 August 2012 (BST) )<br />
* [[Snippets ( Time & Date )| Time & Date ]] ( Last Updated - 14:11, 21 May 2012 (BST) )<br />
<br />
=== Miscellaneous <small>- All Other Examples.</small> ===<br />
<br />
* [[Snippets ( Miscellaneous )| Miscellaneous ]] ( Last Updated - 12:35, 1 August 2012 (BST) )<br />
<br />
=== Networking <small>- Network, Wireless and Internet Examples.</small> ===<br />
<br />
* [[Snippets ( Network )| Network ]] ( Last Updated - 12:33, 1 August 2012 (BST) )<br />
* [[Snippets ( Internet )|Internet ]] ( Last Updated - 12:30, 1 August 2012 (BST) )<br />
* [[Snippets ( Wireless )|Wireless ]]<br />
<br />
=== Windows <small>- Windows Examples.</small> ===<br />
<br />
* [[Snippets ( CMD ) |CMD - Commandline ]]<br />
* [[Snippets ( Files & Folders )| Files & Folders ]] ( Last Updated - 12:16, 1 August 2012 (BST) )<br />
* [[Snippets ( Registry )| Registry ]]<br />
* [[Snippets ( Windows Information )| Windows Information ]] ( Last Updated - 11:27, 30 April 2012 (BST) )<br />
* [[Snippets ( Windows OS )| Windows OS ]] ( Last Updated - 14:35, 21 May 2012 (BST) )<br />
* [[Snippets ( Windows Settings )| Windows Settings ]] ( Last Updated - 12:07, 1 August 2012 (BST) )<br />
* [[Snippets ( Windows Users )| Windows Account Management ]] ( Last Updated - 14:13, 21 May 2012 (BST) )<br />
<br />
== Other Links ==<br />
<br />
[http://www.autoitscript.com/wiki/Free_Software Free Software Written in AutoIt]</div>Czardashttps://www.autoitscript.com/w/index.php?title=AutoIt_Snippets&diff=11459AutoIt Snippets2012-11-19T04:56:35Z<p>Czardas: Changes made to the wording of the first paragraph to improve readfability..</p>
<hr />
<div>Welcome To The AutoIt Snippets Page - ( '''''Snippet - A short reusable piece of computer code''''' ). <br />
<br />
Snippets are generally single functions or small pieces of AutoIt code which can be incorporated into a script to add extra functionality. This section covers a wide variety of subjects and uses. Examples may include anything from finding if an internet connection is working to retrieving the date Windows was installed. This page is intended to give easy access to the functions.<br />
<br />
__TOC__<br />
<br />
[[category:Snippets]]<br />
<br />
{{Snippet Credit Header}}<br />
<br />
== Examples ==<br />
<br />
=== _IsInternetConnected ===<br />
<br />
{{Snippet Header<br />
| AuthorURL=35302-guinness<br />
| AuthorName=guinness<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
ConsoleWrite("Internet Is Connected" & " = " & _IsInternetConnected() & @CRLF) ; ( Returns "True" Or "False" )<br />
<br />
Func _IsInternetConnected()<br />
Local $aReturn = DllCall('connect.dll', 'long', 'IsInternetConnected')<br />
If @error Then<br />
Return SetError(1, 0, False)<br />
EndIf<br />
Return $aReturn[0] = 0<br />
EndFunc ;==>_IsInternetConnected<br />
</syntaxhighlight><br />
<br />
[[#top | ReturnToContents]]<br />
<br />
=== _PasswordCrypt ===<br />
<br />
{{Snippet Header<br />
| AuthorURL=4920-valuater<br />
| AuthorName=Valuater<br />
| ModifierURL=35302-guinness<br />
| ModifierName=guinness<br />
}}<br />
<br />
<syntaxhighlight lang="autoit"><br />
#include <Crypt.au3><br />
<br />
Local $sGenericPassword_1 = 'Password@AutoIt', $sGenericPassword_2 = 'NewPassword@AutoIt', $sSavePath = @ScriptDir & '\License.dat'<br />
ConsoleWrite('1. ' & _PasswordCrypt($sGenericPassword_1, $sSavePath) & @CRLF) ; Write the password to a file located in the @ScriptDir. The password we wrote is returned by the function.<br />
ConsoleWrite('2. ' & _PasswordCrypt($sGenericPassword_1, $sSavePath) & @CRLF) ; Since the password has been written already, we now want to check if the user has entered the password correctly. Returns True or False.<br />
ConsoleWrite('3. ' & _PasswordCrypt($sGenericPassword_2, $sSavePath, 1) & @CRLF) ; Overwrite the old password with a new one.<br />
ConsoleWrite('4. ' & _PasswordCrypt($sGenericPassword_1, $sSavePath) & @CRLF) ; Check the password matches. This will fail as we're checking the old password against the new one.<br />
FileDelete($sSavePath)<br />
<br />
Func _PasswordCrypt($sPassword, $sFilePath, $iOverwrite = 0) ; By guinness, idea by Valuater.<br />
If FileExists($sFilePath) And $iOverwrite = 0 Then<br />
Return BinaryToString(_Crypt_DecryptData(IniRead($sFilePath, 'PasswordKey', 'Password', ''), @ComputerName, $CALG_AES_256)) == $sPassword<br />
Else<br />
If IniWrite($sFilePath, 'PasswordKey', 'Password', _Crypt_EncryptData($sPassword, @ComputerName, $CALG_AES_256)) Then<br />
Return $sPassword<br />
EndIf<br />
EndIf<br />
Return SetError(1, 0, '')<br />
EndFunc ;==>_PasswordCrypt<br />
</syntaxhighlight><br />
<br />
[[#top | ReturnToContents]]<br />
<br />
== Snippet Creation Help ==<br />
<br />
* [[Snippets ( Creation )| Snippets Creation Examples ]]<br />
<br />
== AutoIt Snippets Collection ==<br />
<br />
=== AutoIt <small>- AutoIt Examples.</small> ===<br />
<br />
* [[Snippets ( AutoIt Audio )| Audio Related ]] ( Last Updated - 16:58, 21 May 2012 (BST) )<br />
* [[Snippets ( AutoIt )| AutoIt Miscellaneous ]] ( Last Updated - 12:22, 1 August 2012 (BST) )<br />
* [[Snippets ( AutoIt Array )| AutoIt Array Related]] ( Last Updated - 13:17, 21 May 2012 (BST) )<br />
* [[Snippets ( AutoIt Mouse & Keyboard )| AutoIt Mouse & Keyboard ]] ( Last Updated - 07:52, 3 August 2012 (BST) )<br />
* [[Snippets ( AutoIt String )| AutoIt String Related ]] ( Last Updated - 12:45, 1 August 2012 (BST) )<br />
<br />
=== GUI <small>- Anything GUI related.</small> ===<br />
<br />
* [[Snippets ( Checkboxes )| Checkboxes & Radio ]]<br />
* [[Snippets ( GUI )| GUI ]] ( Last Updated - 12:11, 1 August 2012 (BST) )<br />
* [[Snippets ( Graphics )| Graphics And Images ]] ( Last Updated - 12:37, 1 August 2012 (BST) )<br />
<br />
=== Hardware <small>- Hardware Examples.</small> ===<br />
<br />
* [[Snippets ( Hardware Information )| Hardware Information ]] ( Last Updated - 11:02, 30 April 2012 (BST) )<br />
<br />
=== Numbers <small>- Math, Number & Time Examples.</small> ===<br />
<br />
* [[Snippets ( Math & Numbers )| Math & Numbers ]] ( Last Updated - 12:07, 1 August 2012 (BST) )<br />
* [[Snippets ( Time & Date )| Time & Date ]] ( Last Updated - 14:11, 21 May 2012 (BST) )<br />
<br />
=== Miscellaneous <small>- All Other Examples.</small> ===<br />
<br />
* [[Snippets ( Miscellaneous )| Miscellaneous ]] ( Last Updated - 12:35, 1 August 2012 (BST) )<br />
<br />
=== Networking <small>- Network, Wireless and Internet Examples.</small> ===<br />
<br />
* [[Snippets ( Network )| Network ]] ( Last Updated - 12:33, 1 August 2012 (BST) )<br />
* [[Snippets ( Internet )|Internet ]] ( Last Updated - 12:30, 1 August 2012 (BST) )<br />
* [[Snippets ( Wireless )|Wireless ]]<br />
<br />
=== Windows <small>- Windows Examples.</small> ===<br />
<br />
* [[Snippets ( CMD ) |CMD - Commandline ]]<br />
* [[Snippets ( Files & Folders )| Files & Folders ]] ( Last Updated - 12:16, 1 August 2012 (BST) )<br />
* [[Snippets ( Registry )| Registry ]]<br />
* [[Snippets ( Windows Information )| Windows Information ]] ( Last Updated - 11:27, 30 April 2012 (BST) )<br />
* [[Snippets ( Windows OS )| Windows OS ]] ( Last Updated - 14:35, 21 May 2012 (BST) )<br />
* [[Snippets ( Windows Settings )| Windows Settings ]] ( Last Updated - 12:07, 1 August 2012 (BST) )<br />
* [[Snippets ( Windows Users )| Windows Account Management ]] ( Last Updated - 14:13, 21 May 2012 (BST) )<br />
<br />
== Other Links ==<br />
<br />
[http://www.autoitscript.com/wiki/Free_Software Free Software Written in AutoIt]</div>Czardas