User Defined Functions Standards
This Page contains instructions on submitting UDF's for AutoIt3, it helps me if code is submitted following the below standards and include those 1 +2*n files::
There is as many 2+3 as function to be described.
You will appreciate that we can only include those UDF's that are useful
to a larger group of scripter's.
When you still like your UDF to be included :-) then:
Thanks,
guinness and jpm
User Defined Function coding standards
Function Names
All function names must start with an underscore (“_”). *
Each word in the function name should be capitalized.
The first word of the function name should start with a word describing a
general category such as “Date”, “String”, “Array”, “Network”, etc.. If
the word is too long like “Window”, then an obvious abbreviation may be
used (e.g. “Win” for “Window” or “Net” for “Network”).
All function names must closely resemble the established naming convention
for "internal" AutoIt functions.
Variable Names
The first set of characters after the dollar sign (“$”) should be used to
specify the type of data that will be held in it. The following list
signifies the different prefixes and their data type significance.
$a<letter> - Array (the following letter
describes the data type taken from the rest of the data types below)
$d - Binary data
$h - File or window handle
$id - An AutoIt control Id (GUI)
$i - Integer
$b - Boolean
$f - Floating point number
$n - general number with no preference for floating
point or integer
$s - String
$v - Variant (unknown/variable type of data)
$o - COM object
$p - Pointer. It is assumed that it points to a struct
so no further letters are needed
$t - Structure returned from DllStructCreate()
$tag - Struct definition string. Structure definitions
should conform to the structure guidelines
The rest of the name uses capitalized words to describe the function of
the variable. Names like “$iC” are unacceptable. "$aiWeekDayNames" or
"$iCounter" are much preferable.
All variables must be declared at the beginning of the UDF with a “Local”
scope and before they are used for the first time.
This convention apply also to Local/Global variables. Global variables
must have an extra first letter "g". UDF global variables must start with
underscore.
Const/Enum variables are better if they are defined in UpperCase to
illustrate that they cannot be changed. First letter of the constant is
optional, $e can be used.
Note: Global variables should only be used if they are called from more than one function or used in another scope. For example if the variable is only used in main scope regardless of not in a fuction, then it should be declared using Local.
The “Dim” or “Global” keywords are ambiguous inside of a UDF and as such should be avoided, all variables should be transferred via the Function Parameters using Byref when the updated value needs to be returned.
Parameters
The parameter names must use the same naming conventions as variables.
All parameters must be checked for validity and return appropriate error
codes.
If parameters are used to pass data back to the calling script (ByRef),
then the documentation should explicitly describe said behavior.
Function Documentation
All UDFs must have a documentation header in the script in the following
form:
; #FUNCTION# ;=============================================================================== |
Function Helpfile Documentation
All submitted UDFs must include 1 extra file to be able to incorporate
them in the Helpfile:
FunctionName.txt. This is the example to be
used to build the Helpfile page for AutoIt.chm
###User Defined Function### Name goes here. ###Description### One-line description ###Syntax### #include <NewUDF.au3> |
FunctionName.txt. This is
the example to be used to build the Helpfile page for AutoIt.chm
(Example):
###User Defined Function### _DateDiff ###Description### Returns the difference between 2 dates, expressed in the type requested ###Syntax### #include <Date.au3> _DateDiff ( $sType, $sStartDate, $sEndDate ) ###Parameters### @@ParamTable@@ $sType One of the following: D = Difference in days between the given dates M = Difference in months between the given dates Y = Difference in years between the given dates w = Difference in Weeks between the given dates h = Difference in hours between the given dates n = Difference in minutes between the given dates s = Difference in seconds between the given dates $sStartDate Input Start date in the format "YYYY/MM/DD[ HH:MM:SS]" $sEndDate Input End date in the format "YYYY/MM/DD[ HH:MM:SS]" @@End@@ ###ReturnValue### @@ReturnTable@@ Success: Difference between the 2 dates. Failure: 0 and sets the @error flag to non-zero. @error: 1 - Invalid $sType 2 - Invalid $sStartDate 3 - Invalid $sEndDate @@End@@ ###Remarks### See <a href="_DateTimeSplit.htm">_DateTimeSplit()</a> for other possible variations of the start and end date formats. ###Related### _DateAdd, _DateTimeSplit, _DateToDayOfWeek, _DateToDayOfWeekISO, _DateToDayValue, _DayValueToDate, _NowCalc ###Example### @@IncludeExample@@ _NowCalc |
FunctionName.au3. This is the example to be
included in the Helpfile
#include <Date.au3> |