Good coding practices in AutoIt

[BrewManNH]

I have a question, that probably comes down to more of an opinion than anything else.
 
Is it better to return an array from a function or a struct with named parameters? Case in point would be the UDF in my signature ">Customizable Splashscreen GUI w/Progress Bar". That function returns an array with 3 elements, one is the handle of the GUI, the second is the control ID of the progressbar, and the third is the control ID of the label. As it is currently written, you have to remember that the return value in element 0 is the GUI handle, and element 1 is the control ID of the progressbar, etc.
 
 
If I created a struct in the function like this, and returned that struct instead of the array it does now.

Local $PBMarquee = DllStructCreate("hwnd hWnd;int Progress;int Label")

All you'd have to remember is to use the name of the struct's elements to access its contents.
 

GUICtrlSetData(DllStructGetData($Return, "Progress"), $I)

Instead of this
 

GUICtrlSetData($Return[1], $I)

So, I'm wondering, what would you do in this case? What would be the "best practice" approach?
 

[Melba23]

BrewManNH,

I remember that Valik was absolutely opposed to using structs for data storage other than when necessary for DLL calls. I cannot remember exactly why he was so against such use but his comments were, if I recall correctly, even more caustic than usual.

In such matters I regarded him as a pretty good touchstone - but as a hobbyist coder I am always open to persuasion when it comes to matters like this.

M23

Edit: Found the thread as soon as I looked.

Edited December 24, 2013 by Melba23

[BrewManNH]

I read it, and he seems to be very much against it. But what is the downside of doing it this way, other than I'm not using it in a DLLCall situation? That was never made clear in that thread. I'm always open to changes, as long as the changes are explained as to why I shouldn't do it this way or that way. I'm obstinate I guess.

I'm not a programmer by trade, just a hacker, so things have to be explained in a manner I can understand. 

[jaberwacky]

I like to return autoit3objects from functions in these situations.

[trancexx]

Using dllstructs that way goes directly against the typing paradigm of the language. On top of that dllstruct is not safe type because data is also accessible through pointer.

It's very simple, if you are using dllstruct with/for anything that doesn't absolutely need it then you are abusing it.

[BrewManNH]

Ok, I kind of understand it now.

The next question would be should I be using an array there, as it does now, or is there another method that doesn't require knowing which piece of data is in which element of the array? Something that would work like the struct does, but is safer to work with? An associative array would work, but you'd need to define the element names outside of the function that it's being returned from, which defeats the purpose somewhat.

[trancexx]

Ok, I kind of understand it now.

The next question would be should I be using an array there, as it does now, or is there another method that doesn't require knowing which piece of data is in which element of the array? Something that would work like the struct does, but is safer to work with? An associative array would work, but you'd need to define the element names outside of the function that it's being returned from, which defeats the purpose somewhat.

One doesn't need to be rocket scientist to see that advanced AutoIt usage screams for such composite built-in data type. That's the future.

...Speaking of which, I made Jon remove perfectly suitable (almose ideal) Table type just the other day because he was going nowhere with it.

[jaberwacky]

For instance, a user would use _ChooseFont to return an array of font properties of the chosen font.  Then that array would go into this function:

Func scg_view_font_properties(Const $this, Const $font_properties)
  Local Const $bold_property = (($font_properties[4] = 400) ? "notbold" : "bold")

  Local Const $italics_property = ((BitAND($font_properties[1], 2) = 2) ? "italics" : "notitalics")

  Local Const $underlined_property = ((BitAND($font_properties[1], 4) = 4) ? "underlined" : "notunderlined")

  Local $o_font_properties = _AutoItObject_Class()

  $o_font_properties.AddProperty("Name",    $elscope_readonly, $font_properties[2])

  $o_font_properties.AddProperty("Size",    $elscope_readonly, $font_properties[3])

  $o_font_properties.AddProperty("Bold",    $elscope_readonly, $bold_property)

  $o_font_properties.AddProperty("Italics", $elscope_readonly, $italics_property)

  $o_font_properties.AddProperty("Underlined", $elscope_readonly, $underlined_property)

  Return $o_font_properties.Object
EndFunc

The result of which could be used something like this: ConsoleWrite($fontProperty.Name & @CRLF)

[this-is-me]

The way that has worked for me is totally using Enum and Arrays. The only "problem" with my method is that you have to declare the enum values globally (which for some reason a few don't want to do). I've even begun to use them to help me describe built-in functions.

Example:

Enum $fontFace, $fontWeight, $fontSize, _
    $fontMax
Global $font[$fontMax]

Example()
Func Example()
    $font[$fontFace] = "Tahoma"
    $font[$fontWeight] = "Bold"
    $font[$fontSize] = 8.5
    MsgBox(0, "", GetFontWeight())
EndFunc

Func GetFontWeight()
    Return $font[$fontWeight]
EndFunc

Example with built-in function:

Enum $posLeft, $posTop, $posWidth, $posHeight

MsgBox(0,"",GetPosition("Untitled - Notepad")[$posLeft])

Func GetPosition($title)
    Return WinGetPos($title)
EndFunc

[guinness]

Well you could declare them locally. This practice is already demonstrated in the help file under Enum.

[nbi]

I have been researching AutoIt naming conventions and have been wondering about the leading underscore on function names. I've been trying to make my code adhere to established conventions but I'm not sure what those conventions are. All I have found is this in the UDF standards:

"All function names must start with an underscore (“_”). *" (but there's no footnote text associated with that asterisk providing an explanation for this convention)

If all UDF names have a leading underscore, then why do some internal functions in the examples also have them? For instance, there is "_MyWindowProc" in the "_WinAPI_CallWindowProc" help-file example and "_KeyProc" in the "_WinAPI_SetWindowsHookEx" example.

An exhaustive search has turned up little. Others are also wondering about the style in general:

----------------------------

In a lot of languages with simple OO capability (PHP 4), or misunderstood OO capabilities (Javascript, C using function pointers, etc.), you'll end up with a function naming convention that uses leading underscores to to indicate privilege level.

//ex.
function _myPrivateFunction(){
}

While individual teams are always going to come up with their own naming conventions like this, the underscore convention seems so prevalent that it made me curious about:
1. Where the technique first came from
2. If there was ever any standardized systems (sort of like hungarian notation) developed around the convention
Beyond pure curiosity, I'm seeing this in a few codebases I'm dealing with right now, and I'd like to understand the possible headspaces of the developers who originally came up with it.

----------------------------

While looking over various PHP libraries I've noticed that a lot of people choose to prefix some class methods with a single underscore, such as

public function _foo()

...instead of...
public function foo()

I realize that ultimately this comes down to personal preference, but I was wondering if anyone had some insight into where this habit comes from.

My thought is that it's probably being carried over from PHP 4, before class methods could be marked as protected or private, as a way of implying "do not call this method from outside the class". However, it also occurred to me that maybe it originates somewhere (a language) I'm not familiar with or that there may be good reasoning behind it that I would benefit from knowing.

----------------------------

 

Answers include the following:

----------------------------

In Python, prefixing names with an underscore is more than just a convention: Symbols starting with an underscore are not imported by default when importing "everything" from a module, therefore the underscore indicates "private" / "internal usage".

----------------------------

underscore ( _ ) stands for a private / protected function or variable.
Don't know WHO actually came up with it, but I know it is "supported" by Zend ( and the Zend coding standards ).

----------------------------

I've seen underscore used as private functions and I've seen seen underscore as global functions. Also underscore is used to denote global variables within PHP itself.

----------------------------

 

And Wikipedia has this:

A common programming convention is to use a leading underscore in a name (for example _name) to indicate that the name is intended for internal use within a library (computing) or a header file and does not appear in an API.

The general consensus is that it's a means of identifying an object as protected or private, but this doesn't seem to match the AutoIt philosophy. I think it would be helpful to shed some light on this topic.

[guinness]

Internal functions: __FuncName()

AutoIt UDF functions: _FuncName()

Your functions: FuncName()

This is how it should be, so as to easily distinguish which are your functions and AutoIt's.

[nbi]

Okay, that helps, thanks.

I thought it would be useful to create an "AutoIt Style Guide" document to consolidate the information available here in this thread, in the "UDF Standards," and elsewhere. I have a collection of links to various style guides, but I just found this one quite by accident:

Style Guide for Python Code

http://legacy.python.org/dev/peps/pep-0008/

It's quite comprehensive and most of it is not language-specific. It's also in the public domain, so we can ask them if we can use whatever is applicable (giving them proper credit, of course). If anyone thinks this is a worthwhile project, I could potentially give it a shot.

Just a thought . . .

[Mat]

One of the most complete style guides I've seen is googles. 

Can't say for definite that it's what google actually uses, but the authors are all ex-Google, or still employed (difficult to tell from a quick google). Some of them are/were major developers in some of googles biggest projects as well so they know what they are talking about.

C++ is far more complex than AutoIt in many ways though, for example look at the scoping section.

[guinness]

Mat has done something like that in the wiki already. Only a few of us actually adhere to it or any practices as a matter of fact.

Edited April 2, 2014 by guinness

[guinness]

18 months ago I started this "best coding practices" thread and I'm happy to say that I can finally see the community taking pride in the code they produce and not using AutoIt as just some "scripting language" it once was.

[mLipok]

Mat has done something like that in the wiki already. Only a few of us actually adhere to it or any practices as a matter of fact.

 

Can you post here a link ? to be sure which one you mean ?

[guinness]

This one >> http://www.autoitscript.com/wiki/UDF-spec

[water]

The headers section should be removed, right?

[guinness]

The headers section should be removed, right?

Why do you say that? If someone submits a worthy UDF then we will need the headers to create the appropriate text docs. Also we still need headers for internal functions as they don't have a corresponding help file section.