UDF-spec: QUESTIONS

[mLipok]

Debugging is something that shouldn't be in a UDF. 

I guess you are talking about:

1. _XML_Misc_ErrorDecription_Reset()
    2. Local $oXML_COM_ErrorHandler = ObjEvent("AutoIt.Error", "_XML_ComErrorHandler_MainFunction")
    3. #forceref $oXML_COM_ErrorHandler

    4. _XML_UseEventHandler($oXML_Document)
    5. __XML_IsValidObject($oXML_Document)
    6. If @error Then Return SetError(@error, @extended, $g__eXML_RESULT_FAILURE)
.....
    x. _XML_Misc_ErrorDecription("Error creating Attribute: " & $sAttribute_Name & @CRLF & 'Reason: ' & $sXPath & " does not exist." & @CRLF)

exactly about 1 and x line or you mean also others ?

 

 

Anyhow, that wiki entry is created by users, for users and not the Dev team.

I think if users as me can learn from Dev team it would be awesome,
So personaly I'm glad that anybody (not only Dev)  keeps his hand on the pulse and sets a good direction.

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

I totally forget to check using if this UDF is using IsArray , thanks for reminder.

 

; _XML_createAttributeute => _XML_CreateAttribute ;

$strComment => $sComment ; ...

Thanks, fixed.

I'll submit today updated UDF.

 

 

[mLipok]

I am cool with it.

Good to hear that.

I would only use For.. In on objects though.

For long time I personally do not use    "For ... In ..."    on array variables, I know I read about it on the forum, but I do not remember where.

 

[mLipok]

I prefer to stay with originall naming so

_XML_CreateAttribute should be _XML_createAttribute 

as you can see it here: https://msdn.microsoft.com/en-us/library/ms764615(v=vs.85).aspx

in the same way:

_XML_DeleteNode >>> _XML_removeChild

In this way people start to learn official XMLDOM methods name.

 

QUESTION: whether it meets the requirements of the UDF-Spec ?

 

 

---

 

I do not want to use magic number.

normally Return values was such kind of description:

 

; Return values .: Success        $__g_eXML_RESULT_SUCCESS
;                  Failure        - $__g_eXML_RESULT_FAILURE and sets the @error 
;                  |1 - Could not create node.
;                  |2 - Mismatch between attribute name and value counts.
;                  |3 - Attribute Name cannot be empty string.

 

But I want to make this like here:

; Return values .: Success        $__g_eXML_RESULT_SUCCESS
;                  Failure        - $__g_eXML_RESULT_FAILURE and sets the @error flag to non-zero (look in #Region XMLWrapperEx.au3 - @ERROR Enums)

I simply do not want to enumerate each @error code

QUESTION: whether it meets the requirements of the UDF-Spec ?

 

Edited September 5, 2015 by mLipok

[guinness]

Well function naming in AutoIt is pascal-case and if people want to learn XML, then the case of the function is not going to stop them. _WinAPI_* functions don't necessarily match the API they're using, but this doesn't stop people looking at the code to learn about the Windows API.

@error return codes are fine as "magic values", since this is the case in most of the UDFs. As for the variable naming of an enumeration it should be UPPERCASE e.g. $XMLWRAPPER_ERROR_YOUDIDSOMETHINGWRONGNOTME.

[mLipok]

As I see in ie.au3

;~ Global Enum Step * 2 _; NotificationLevel
;~         $_IENotifyLevel_None = 0, _
;~         $_IENotifyNotifyLevel_Warning = 1, _
;~         $_IENotifyNotifyLevel_Error, _
;~         $_IENotifyNotifyLevel_ComError
;~ Global Enum Step * 2 _; NotificationMethod
;~         $_IENotifyMethod_Silent = 0, _
;~         $_IENotifyMethod_Console = 1, _
;~         $_IENotifyMethod_ToolTip, _
;~         $_IENotifyMethod_MsgBox

I check UDF-spec and I see that there is only talking about using notification in Examples.

I want to ask about using MsgBox and other notification in UDF.

Edited September 7, 2015 by mLipok
wording

[guinness]

The IE UDF is a mess, please don't use that as a basis for UDF creation.

UDFs should only set @error (or @extended) as ways of logging an error (which MsgBox is essentially, a logging tool). Logging basically should be left to the end-user and not the UDF designer. Imagine if you will your UDF being used in a console based application, how annoying would it be to see a message box popup on error?

[mLipok]

QUESTION:
What about keep notification as disabled by default and require the user conscious enable this kind of feautre ?

I was made this by 

Func _XML_MiscProperty_Notify.......  

which by default have 

Local Static $bDebug_Static = False

And actually I leaves MsgBox only in __XML_Misc_MsgBoxNotifier().
But I think you're right.

It is better to make appropriate mechanisms like the following:

Func _XML_ComErrorHandler_MainFunction($oError)
    __XML_ComErrorHandler_InternalFunction($oError)

    ; Run also UserFunction defined by _XML_ComErrorHandler_UserFunctionName()
    Local $fnFunction = _XML_ComErrorHandler_UserFunction()
    If IsFunc($fnFunction) Then $fnFunction($oError)
EndFunc   ;==>_XML_ComErrorHandler_MainFunction

and do good examples of how to use them.
 

So basicly here are the questions:

Question 1:
Is the UDF should notify the COM Event to the Console, or in any other way - how ?

Question 2:
Is the UDF should notify the COM Error, to the Console, or in any other way - how ?

Question 3:
Is the UDF should include any notifications (different than @error @extended and ReturnValue ) ?

Question 4:
Is the UDF Documentation should include examples of how such notifications should be done in user scripts ?

Question 5:
Is the UDF should include function which change $UDFNAME_ERROR_... to human readable description ? (Like my: _XML_Misc_ErrorParser )

Question 6:
Could you expand a UDF-Spec with a description about how notification should be made in UDF ?

 

Edited September 7, 2015 by mLipok
Question 3 added comment

[mLipok]

The IE UDF is a mess, please don't use that as a basis for UDF creation.

Good to know.
The more that one day someone will do a new UDF for Microsoft Edge

 

[guinness]

Considering this Global Debug override used to be in most of the UDFs and was removed prior to v3.3.10.0, I don't think it's best to go backwards. So no, I don't like that idea.

Answers to your questions:

1. How does Word or Excel do it?
2. Same question.
3. No, only set @error if an error exists AND/OR @extended if additional information is required that is out of context of the @error macro. The return value should be meaningful to the function, but general speaking to determine the type of error occurred, use an @error code and return value as Null (or something similar)
4. Examples of for demonstrating functions, not documentation.
5. Up to you, but considering this isn't done in the AutoIt UDFs, I would go with no, as it only bloats the UDF for something that is unlikely to be used.
6. The best source of documentation is looking at the UDFs in my humble opinion. Also if someone feels having message boxes and console write lines in UDFs is a good approach to displaying an error, then maybe creating UDFs is not for them.

[mLipok]

 

 

Considering this Global Debug override used to be in most of the UDFs and was removed prior to v3.3.10.0, I don't think it's best to go backwards. So no, I don't like that idea.

I did not have in this regard such knowledge, now I see that it really should not come back.

1. How does Word or Excel do it?

Func __Excel_COMErrFunc()
    ; Do nothing special, just check @error after suspect functions.
EndFunc   ;==>__Excel_COMErrFunc

Func __Word_COMErrFunc()
    ; Do nothing special, just check @error after suspect functions.
EndFunc   ;==>__Word_COMErrFunc

But I do not think this is the best way as in this case user can not handle this errors at all.

For this reason I make it like this:

Func _XML_ComErrorHandler_MainFunction($oError)
    ; Run UserFunction defined by _XML_ComErrorHandler_UserFunctionName()
    Local $fnFunction = _XML_ComErrorHandler_UserFunction()
    If IsFunc($fnFunction) Then $fnFunction($oError)
EndFunc   ;==>_XML_ComErrorHandler_MainFunction

And Examples should show how to use it.

 

1. How does Word or Excel do it?
2. Same question.

There is no EVENT handling implemented for Word and Excel UDF.

I think this should only be wrapper to user specified functions.

And Examples should show how to use it.

 

3. No, only set @error if an error exists AND/OR @extended if additional information is required that is out of context of the @error macro. The return value should be meaningful to the function, but general speaking to determine the type of error occurred, use an @error code and return value as Null (or something similar)
4. Examples of for demonstrating functions, not documentation.

Ok

5. Up to you, but considering this isn't done in the AutoIt UDFs, I would go with no, as it only bloats the UDF for something that is unlikely to be used.

I decide to move appropriate functions to the examples.

 

6. The best source of documentation is looking at the UDFs in my humble opinion. Also if someone feels having message boxes and console write lines in UDFs is a good approach to displaying an error, then maybe creating UDFs is not for them.

These MsgBox and ConsoleWrite was in the UDF from the beginning. Now I clean up.

To clarify:
I asked if you could put in the UDF-Spec information about it is that the UDF should not be used any notification other than "error" and "extended" and any abot that notifications which use MsgBox and ConsoleWrite are a matter of the user.

 

[guinness]

The UDF-spec isn't locked down, anyone can edit it.

[kylomas]

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

Wow...it must have driven you nuts when I was using $1, $2, $3...I stopped in deference to Guinness. 

Joking aside, from a non-programmers (professionally) point of view there seems to be a tipping point between productive and non-productive variable naming practices.  I wonder where that point is?  As a layman I might say, "the shortest name that describes the type, scope and use".  A naïve point of view but possibly part of a larger principle.

If I am wide of the scope, pun intended, of this thread, then my apologies!

kylomas   

[mLipok]

No problem @kylomas as this is topic about UDF-spec and how to make them well.
I remember there was many places where variable naming was discused, but trully I do not rember any disscusion about  variables used in For ... loops.

As a layman I might say, "the shortest name that describes the type, scope and use".  A naïve point of view but possibly part of a larger principle.

No this is very good point of view.

But as you say: "the shortest name that describes the type, scope and use", I want to ask you which one of the following example fits your words ?

 

; Example 1
For $x in $oFolders
    ; .....
    For $y in $oFiles
        ; .....
        If $bSomeTest Then FileCopy($y, $x)
        ; .....
    Next
    ; .....
Next

; example 2
For $oFolder in $oFolders
    ; .....
    For $oFile in $oFiles
        ; .....
        If $bSomeTest Then FileCopy($oFile, $oFolder)
        ; .....
    Next
    ; .....
Next

; example 3
For $oFolderEnum in $oFoldersColl
    ; .....
    For $oFileEnum in $oFilesColl
        ; .....
        If $bSomeTest Then FileCopy($oFileEnum, $oFolderEnum)
        ; .....
    Next
    ; .....
Next

 

EDIT:
and the second question: 

Which example of If $bSomeTest Then FileCopy(.........)    shows the best way what exactly will happen with the files ?

 

EDIT 2:

As a curiosity to say that recently one of the variables in my program had a name longer than 100 characters.
This may seem strange but it was one of the many variables and have to show the way to use it (the names of all modules).

Edited September 7, 2015 by mLipok

[kylomas]

I would use example #2.  I don't see where you are going with the collection numbering scheme.  Also, we are talking about code that will be promoted in some way (production, general use, part of a larger project, etc).

When I'm doing proof of concept crap I might do

for $1I in $1C...

Poor practice but I change it later if the code is viable... 

[mLipok]

 

Func __Excel_COMErrFunc()
    ; Do nothing special, just check @error after suspect functions.
EndFunc   ;==>__Excel_COMErrFunc

Func __Word_COMErrFunc()
    ; Do nothing special, just check @error after suspect functions.
EndFunc   ;==>__Word_COMErrFunc

But I do not think this is the best way as in this case user can not handle this errors at all.

For this reason I make it like this:

Func _XML_ComErrorHandler_MainFunction($oError)
    ; Run UserFunction defined by _XML_ComErrorHandler_UserFunctionName()
    Local $fnFunction = _XML_ComErrorHandler_UserFunction()
    If IsFunc($fnFunction) Then $fnFunction($oError)
EndFunc   ;==>_XML_ComErrorHandler_MainFunction

And Examples should show how to use it.

 

What about this ?
 

I wonder also what @water thoughts about this ?

 

[mLipok]

I would use example #2.  I don't see where you are going with the collection numbering scheme.  Also, we are talking about code that will be promoted in some way (production, general use, part of a larger project, etc).

I would prefer example #3, because when you see inside script such line:

If $bSomeTest Then FileCopy($oFileEnum, $oFolderEnum)

Then you do not must to wonder but you just know "this is in loop mode, so there be copied multiple files to multiple folders"

 

[water]

I wonder also what @water thoughts about this ?

I'm far too busy at the moment to spend the time this subject needs. I'm not really happy with the new approach but I need time to think about it so I can suggest a "better" one.

[mLipok]

I'll be waiting patiently for your comment.