UDF-spec: QUESTIONS

[mLipok]

UDF-spec is actually defined here: https://www.autoitscript.com/wiki/UDF-spec
I always want to ask many questions about UDF-spec, in particular in relation to: https://www.autoitscript.com/wiki/Best_coding_practices

Now when I submit:

My questions came back to my mind, at least in part.

 

Question 1:

The first of what I would like to ask is:   Why the specification says nothing about using:

#Region some description.....
.... 
#EndRegion

??

I use them more and more, as in the above UDF.

 

Question 2:
How to distinguish global variables within the UDF from other global variables, I think the main script?
I know that basically specification applies to the UDF, but must remain in some kind of relationship with the main part of the script, and the principles of good coding defined in the above mentioned link.

 

Question 3:
here https://www.autoitscript.com/wiki/UDF-spec#Other_Sections
is some important part about variables and constants, I do not see any information about Enums .

So I want to ask : How to properly use enums ?

 

 

---

I would be pleased for answering those questions.

mLipok

 

Edited September 3, 2015 by mLipok
wording

[mLipok]

Question 2:
How to distinguish global variables within the UDF from other global variables, I think the main script?
I know that basically specification applies to the UDF, but must remain in some kind of relationship with the main part of the script, and the principles of good coding defined in the above mentioned link.

 

Sorry for the question I see that this is defined in:

https://www.autoitscript.com/wiki/Best_coding_practices#Scopes_of_Variables

 

Variables should also be named according to their scope.

Global UDF variable	Global variable	Local variable
$g__iSomeVar	$g_iSomeVar	$iSomeVar

With this method, you will avoid non wanted re-assignments.

 

 

But I see there is inconsistency on how to write scope of variables, as the UDF-Spec define it as:

... naming pattern: $__g<VARNAME>_<UDF> where <VARNAME> is the name as it ....

 

as you can see the "g" letter It is in a different position from the beginning of the name.

 

[BrewManNH]

Read the discussion section of the UDF wiki page, you'll see that the "standard" listed there isn't to be taken as a standard. To be completely honest, I don't believe there is a standard naming convention used in the standard UDFs, although not for lack of trying.

[mLipok]

Read the discussion section of the UDF wiki page, you'll see that the "standard" listed there isn't to be taken as a standard.

I do not know what exaclty you mean. Can you post a link / screenshot or some more description ?

To be completely honest, I don't believe there is a standard naming convention used in the standard UDFs, although not for lack of trying.

I saw that. For example in array.au3

Global $g_oArrayUniqueCOMErrorHandler = 0

is this should be:

Global $g__oArrayUniqueCOMErrorHandler = Null

?

and
in ie.au3

Global $__g_bIEAU3Debug = False
Global $__g_oIEErrorHandler, $__g_sIEUserErrorHandler

is this should be:

Global $g__bIEAU3Debug = False
Global $g__oIEErrorHandler = Null , $g__sIEUserErrorHandler = Null

 

[BrewManNH]

I do not know what exaclty you mean. Can you post a link / screenshot or some more description ?

https://www.autoitscript.com/wiki/Talk:UDF-spec#Variable_naming_conventions

 

Global $g_oArrayUniqueCOMErrorHandler = 0

is this should be:

Global $g__oArrayUniqueCOMErrorHandler = Null

I personally don't agree that using one or two underscores is a good way of distinguishing between a global in a UDF or a global in the main script. It's far too easy to get them confused and adds nothing to making the script easier to follow. Especially if you're trying to read it quickly, you could mistake one for the other MUCH too easily. I tend to think that the global variable name in the IE udf makes it much simpler to see that it is a UDF global and not one from the main script. But this is merely my opinion and I have no control over how variables get named anywhere.

[Melba23]

mLipok,

Stop trying to overthink things - get the code working first and then worry about tidying up small details such as variable naming. Anyway, whenever it comes to trying to get everything exactly the same I always follow the example one of my old bosses and quote Ralph Waldo Emerson (well, the first few lines at least).

M23

[mLipok]

To be completely honest, I don't believe there is a standard naming convention used in the standard UDFs, although not for lack of trying.

 

After reading your comments, I would like to mention something more generally, what I forgot to write the introduction.
Well, I'm not going to complain about the currently available standard UDF file, or on anyone's published anywhere.
I just want to know how to properly write code, so that it is understood by everyone and equal in terms of appropriate methodology.

As indeed it was raised earlier eg. In the thread quoted at the beginning (XMLDomWrapperEx) in the future it would be good to have the XMLDomWrapperEX UDF as a standard.

In fact, I work even on many others, I change my own so as to have a better level, and working also with others UDF, for example, I have intensively working on: _sql.au3 which will eventually want to change to ADO.au3.

I also have a design and a bit of work devoted to the modification of one of the standard UDF.

 

https://www.autoitscript.com/wiki/Talk:UDF-spec#Variable_naming_conventions

Thanks, now I see that I was blind

......

now I notice @Melba23 post. 

The last sentense "To be great is to be misunderstood." is the best (for me of course).

 

EDIT:
after lecture:

https://www.autoitscript.com/wiki/Talk:UDF-spec#Variable_naming_conventions

I see I must re read :

 

 

Edited September 3, 2015 by mLipok
wording

[guinness]

To be completely honest, I don't believe there is a standard naming convention used in the standard UDFs, although not for lack of trying.

There was but it wasn't enforced by those who pushed the libraries to AutoIt. jpm and myself have been doing a lot of refactoring as now a standard has been reached and can be see in the README (see help file sources OR wiki page).

@mLipok, I have updated the best practices wiki entries with some minor fixes. Global UDF variables (according to our latest README in the repo) and how they're named in the UDF, should be $__g_. The beta Array UDF is not using that global variable anymore, but correct, it should have been $__g_. My fault for not seeing that.

Edited September 4, 2015 by guinness

[mLipok]

Thanks

 

EDIT:

so for now it should be :

Global UDF variable	Global variable	Local variable
$__g_iSomeVar	$g_iSomeVar	$iSomeVar

 

and again thanks ... for claryfication.

 

Edited September 4, 2015 by mLipok

[mLipok]

so in UDF-Spec 

... naming pattern: $__g<VARNAME>_<UDF> where <VARNAME> is the name as it ....

should be also changed ?

 

For example 

$__g_<VARNAME>_<UDF> 

 

And what about such format in ie.au3

Global Enum _; Error Status Types
        $_IESTATUS_Success = 0, _
        $_IESTATUS_GeneralError, _
        $_IESTATUS_COMError, _
        $_IESTATUS_InvalidDataType, _
        $_IESTATUS_InvalidObjectType, _
        $_IESTATUS_InvalidValue, _
        $_IESTATUS_LoadWaitTimeout, _
        $_IESTATUS_NoMatch, _
        $_IESTATUS_AccessIsDenied, _
        $_IESTATUS_ClientDisconnected

 

and one more question 

is it good:

$__g_<VARNAME>_<UDF> 

or it would be better:

$__g_<UDF>_<VariableName> 

 

I prefer the second form, as this is much more readable, so in the code of the main program, and at the UDF section with declaration of variables.

 

 

 

[guinness]

Before I respond, I have just gone through all 19 pages of the best practices thread and updated code that was old and outdated.

 

Global Enum _; Error Status Types
        $_IESTATUS_Success = 0, _
        $_IESTATUS_GeneralError, _
        $_IESTATUS_COMError, _
        $_IESTATUS_InvalidDataType, _
        $_IESTATUS_InvalidObjectType, _
        $_IESTATUS_InvalidValue, _
        $_IESTATUS_LoadWaitTimeout, _
        $_IESTATUS_NoMatch, _
        $_IESTATUS_AccessIsDenied, _
        $_IESTATUS_ClientDisconnected

This is difficult to change as they user be all uppercase e.g. $IESTATUS_SUCCESS, but that would be a script breaking change because of $_ missing. It's one to think about at least.

I have also amended the wiki entry for the UDF specification. It's still work progress of course, but it's there as a good basis.

But in all honesty, if you're using global variables, then you're designing the UDF wrong. I have posted how to not use Global variables, but still maintain data for the duration of the application.

Edited September 4, 2015 by guinness

[mLipok]

Before I respond, I have just gone through all 19 pages of the best practices thread and updated code that was old and outdated.

I've seen.

 

This is difficult to change as they user be all uppercase e.g. $IESTATUS_SUCCESS, but that would be a script breaking change because of $_ missing. It's one to think about at least.

I understand, and no wory about ie.au3 this was only example.

As I say in post #7:

"
Well, I'm not going to complain about the currently available standard UDF file, or on anyone's published anywhere.
I just want to know how to properly write code, so that it is understood by everyone and equal in terms of appropriate methodology.
"

 

I have also amended the wiki entry for the UDF specification. It's still work progress of course, but it's there as a good basis.

Have you noticed my amendment ?

 

But in all honesty, if you're using global variables, then you're designing the UDF wrong. I have posted how to not use Global variables, but still maintain data for the duration of the application.

actually in in XMLDomWrapperEx I'm using only:

Global $g__oXMLDOM_Events = Null

How you see this is not for ERROR handler but for EVENT Handler, as I'm actually not sure if it can be also done as local scope (must check few things), and I think there is no need to do that,       as Events must be declared per single AcitveX object, so there is no possibility for any problems with naming variables and overlapping of functions which should support the Event by various UDF.

 

edit.

all others Globals are const or enums.

 

 

Edited September 4, 2015 by mLipok

[guinness]

I just checked your changes and they're great. About the global variable leave it if you think it's worthy of being there.

[mLipok]

Now I have other question about UDF-Spec:

there is

Global Const $tagMYSTRUCT = "ptr hFoo; int iBar"

 

Question: how in relation to BestCodingPractice   TagStructure   should be properly declared in Global scope ?

I'm asking is this following declaration is proper :

Global Const $__g_tagMYSTRUCT = "ptr hFoo; int iBar"

 

[mLipok]

@guinness I just notice 

https://www.autoitscript.com/w/index.php?title=UDF-spec&diff=13224&oldid=13223

that you remove from:

$__g_<VARNAME>_<UDF> 

_<UDF>

and now it is:

$__g_<VARNAME> 

It was intentional ? If so .. why ?

 

[guinness]

Because our README doesn't specify this...

This convention applies also to Local/Global variables. Global variables must have an extra first letter "g" e.g. g_sVar. UDF global variables must start with an underscore e.g. $__g_sVar.
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 function, then it should be declared using Local.

So you could do $__g_oXMLEvents OR $__g_oXMLWrapperEvents and that would be fine.

Edited September 4, 2015 by guinness
Changed to plain text

[mLipok]

So now there is some inconsistency:

.....These are named $Debug_<UDF> although the <UDF> part .....follow the naming pattern: $__<UDF>CONSTANT_<NAME>......

 

and this 

 This ensures there will never be a conflict with user variables of other UDF globals.

became not always true statement.

 

 

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 function, then it should be declared using Local.

Please add note that ErrorHandler also should be in local scope, EDIT: of course if this is official recommendation

btw.
Did you look at my implementation of LOCAL error handling   in _XMLDOMWrapperEx.au3

 

Edited September 4, 2015 by mLipok

[guinness]

Debugging is something that shouldn't be in a UDF. Anyhow, that wiki entry is created by users, for users and not the Dev team.

As for looking at your code, I have now very quickly. Something like this...

Func _XML_ArrayAdd(ByRef $avArray, $sValue)
    If IsArray($avArray) Then
        ReDim $avArray[UBound($avArray) + 1]
        $avArray[UBound($avArray) - 1] = $sValue
        Return SetError($g__eXML_ERROR_OK, 0, $g__eXML_RESULT_SUCCESS)

    Else
        Return SetError($g__eXML_ERROR_GENERAL, 0, $g__eXML_RESULT_FAILURE)

    EndIf

EndFunc   ;==>_XML_ArrayAdd

can be refactored to this..

Func _XML_ArrayAdd(ByRef $avArray, $sValue)
    Local $iUBound = UBound($avArray) 
    If $iUBound Then ; IsArray() only tells you if it's an array data structure and not if elements are in the array.
        ; Cache function call results, as function calls are expensive compared to variable lookups.
        ReDim $avArray[$iUBound + 1]
        $avArray[$iUBound - 1] = $sValue
        Return SetError($g__eXML_ERROR_OK, 0, $g__eXML_RESULT_SUCCESS)
    EndIf
    
    ; Else is not required, as this was always happen as a last resort.
    Return SetError($g__eXML_ERROR_GENERAL, 0, $g__eXML_RESULT_FAILURE)
EndFunc   ;==>_XML_ArrayAdd

; _XML_createAttributeute => _XML_CreateAttribute
; $strComment => $sComment
; ...

 

[mLipok]

I start using this convention:

if variable is ObjectsCollection then variable name ends with sufix "Coll"
variable used in loops are named with sufix "_idx" like this       For $iAttribute_idx = 0 To $oAttributesColl.length - 1
variable used in loops are named with sufix "Enum" like this    For $oNodeEnum in $oNodesColl

As I hate whe the IteratedIndex or EnumeratedObjects are named like $x $i or $y ,  eventualy   $oItem,

Here  you can see some part which was totaly mess, and confusing when you try to analyze.

For $nodeOld In $oldNodes

            ; Create a New element
            $nodeNew = .createNode($NODE_ELEMENT, $objNewNode, $ns)

            ; Copy attributes
            For $nodeTemp In $nodeOld.Attributes

so for now I change it to this:

For $oNodeEnum_Old In $oNodesColl_Old
            ;Create a New element
            $oNodeNew = .createNode($NODE_ELEMENT, $oNode_NewIndicated, $sNameSpace)

            ;Copy attributes
            For $oAttributeEnum In $oNodeEnum_Old.Attributes

 

What you think about such coding practice ( I mean using "_idx" and "Enum" suffix in "For loops" ).

 

[guinness]

I am cool with it. I would only use For.. In on objects though.