autoit wiki guideline clarification

[donnyh13]

Good day all,
I am here hoping to obtain some clarification on a couple of things in the wiki help/ guidelines....
First:
Quote " 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."
https://www.autoitscript.com/wiki/Best_coding_practices

Quote 2:" For code readability, there are special rules dealing with variables, particularly naming. All variables should be declared at the beginning of their scope, which usually means at the start of the function in which they are used, ..."
https://www.autoitscript.com/wiki/UDF-spec

So.... my interpretation: it Is best, when coding for yourself, to not hog memory, and declare varibles at the time of need.  BUT -- If you are coding for sharing to others, its best to hog as much memory as possible,  by declaring all variables at the top of a function,  even if they're optional variables, for readabilities sake.. am I missing something?  Hidden "in this case do that" kinda thing?

Second: in the udf spec wiki pages it mentions the following:
" There are some flags that can be used within function headers:
    + in column 20 is the continuation flag for the previous line (used in Parameters, Return Values)
    | in column 20 is a new line in the right side of the table when the help file is generated (used in Parameters, Return Values)
    - in column 20 will create new row in the table, used for things like Defaults for a style (used in Parameters, Return Values)
    + in column 2 of Remarks is a blank line"

Is there some examples/ explanation on this? What does the | new line vs - new row etc look like written in the udf header vs help file ?

Thirdly:

" Index....
" Other Sections
Other sections, in order of appearance, are as follows.
Variables....
Constants....
Listing
This defines all functions and structures currently used in the library. It MUST be the second defined header item after #Index. "

https://www.autoitscript.com/wiki/UDF-spec

So... which is to appear in what order exactly?

Sorry for the possibly stupid questions,  perhaps it's clear to a experienced coder?

Thank you for any clarification.
Don

 

[donnyh13]

I'm guessing nobody has any clarification?

[Jos]

4 hours ago, donnyh13 said:

I'm guessing nobody has any clarification?

Just code like you prefer and don't worry about opinions of others.  

[abberration]

Hello, 

I am not the best person to answer your questions, but I have been using AutoIt for years. I have read over the best practices guidelines, but that has only been recently (in the past 6 months or so). I have posted many scripts in the past and no one has ever mentioned that I wasn't adhering to the best practices. They are good rules to follow and can save some headaches, because the rules have pointed out some things that can break a script and leave you scratching your head. 

Your questions about variables are taken from Best Coding Practices and UDF Specific are talking about different things. In Best Coding Practices, I think it simply means not to initialize all variables at the beginning of your script, meaning if you have functions that will have local variables that won't be used anywhere else, declare them inside those functions. As for the UDF Specific, it is talking about the best consistency for writing a UDF so other people will not get confused. I think UDF guidelines are important because other people may need to modify your UDF for their own needs or may continue or fix a UDF if it is abandoned and never updated. The UDF guide simply states the order and structure in which things should be listed. The best example of a UDF is at the bottom of that page called Template UDF. 

As for your question about the +, | and - in UDF headers, the Template UDF shows examples of the - and | being used in the tables for Parameters and Return values:

; Parameters ....: $avAnArray       - [byref] An array of anything. The value of anything is changed and passed out using this
;                                     parameter. The array should only have one dimension
;                  $iAnInt          - An integer that does very little.
;                  $hAHandle        - [optional] A handle. Default is zero.
;                  $nSomeNumber     - [optional] A number of some kind. Default is 42.
; Return values .: Success          - A MYSTRUCT structure.
;                  Failure          - Returns zero and sets the @error flag:
;                                   |1 - The $avAnArray is invalid.

As for your third question about the order of things listed in an UDF, look at the Template UDF again and it is consistent with the statements that #Index# comes first, then other sections, which includes the listing of functions and structures immediately after #Index#. The guide probably should have put that section at the top of of the Other Sections, but they did get it correct in the Template UDF. 

Personally, I wouldn't worry about the UDF stuff until you are good at coding and are ready to write and share UDFs with other people. 

The best practices are great if you plan to share your code on the forum or if you plan to use your scripts professionally (i.e., at your job), but if you are just scripting for your own use, as Jos said, just code for yourself. For myself, I think the best advice I can give is to write code that isn't sloppy and to make good comments to remind yourself why you did something or what a piece of code does. I have spent a lot of time trying to figure out what my old code did. Just like the help file is an incredible piece of documentation, your comments are also great documentation. 

I hope this helps. If anything is still unclear, I will try to explain further.

Cheers!

[donnyh13]

Thank you @Jos for your encouragement!

Thank you @abberration, I appreciate your time in writing out such a detailed response!

Thank you for the clarification on the variable declaration,  I see what that was getting at now. And also the guidance on UDF listing order. I did see the UDF template but wasn't sure which direction to go with. I also did see the - & | in the template,  but, unless I'm mistaken, or its not rendering right, those marks aren't in the 20th column? Or can they be used as flags in any column 20 and over?

Its good to hear your experience in posting scripts, to be honest, the reason these questions came up is I was working on making a UDF I am actively working on in my "spare" time to be in compliance with both the guidelines and the udf specs pages on the wiki before I post it. So far the udf is 2000 lines and I wasn't wanting to have to re correct it again if I misunderstood something. I think I have a better idea on what to do now. Thanks!