Best Coding Practices

[coffeeturtle]

15 hours ago, PeteF said:

 

I would also be interested in  your Guide, PeteF. Thanks!

[PeteF]

15 hours ago, LarsJ said:

PeteF, You can try to look at this. I have not read it myself, but it's quite popular.

I looked at the above recommended help resource and in the description it states; "  It follows along with the help file for the most part – but provides additional context and attempts to connect all the information in a cohesive way for someone without any programming experience.  "

----

So my idea of a Quick Start Guide is nothing like that. My idea is to have a a quick start guide that is aimed at the experienced programmer who does not require tutoring in the basics of programing. In other words, don't teach me about how to program such things as For/Next or While/Wend or my own Functions, just show me what's different from the way I've been programing for the last 10 years in VB6.  

For example, a VB6 programmer comes along and starts looking for an equivalent  "Goto" statement in AutoIt. The current AutoIt Help files are void of any such command and lots of time is wasted by the VB6 expert who is new to AutoIt.  So my idea it to point these kinds of thing out and not duplicate what others have done to teach basic AutoIt programming skills.

It's going to be a relatively short document of 20 pages or less aimed at a niche group of experienced programmers who decided they'd like to get started using AutoIt.

That's why I asked, what percentage of members here on the forums fall into the category of being experienced programmers who are relatively new to AutoIt?  What is the demand?  Would I be providing another useful resource to the community?

Good idea?  Bad idea?  I'm all ears.

-pete-

Edited December 2, 2016 by PeteF

[iamtheky]

If you build something that would have helped you, chances are it would help someone else.  Opining will most likely bring far more counterpoints than support, because we are trained to come to these forums find problems and fix things.

[PeteF]

15 hours ago, JLogan3o13 said:

Just realize that the Wiki really serves as our "Quick Start Guide" because it is continually updated.

Just to clarify what I mean by a "Quick Start Guide", I'm referring to a guide that is brief and only provides the most essential information to get an experienced programmer up and running ASAP.

This.. Welcome to the AutoIt Wiki.. https://www.autoitscript.com/wiki/   is nothing like a Quick Start Guide, as it is more on the detailed side or a comprehensive work.

Think of last time you purchased a printer or other PC hardware that included a Quick Start Guide (a single sheet of folded paper containing just enough info to get it going) and also a detailed manual of 100 pages. Now you should have a better picture of what I'm talking about creating in ways of a Quick reference document. But understand, it's aimed at the experienced programmer and more specifically, the VB6 or VBA programmer. 

For this to work, I have to write it now, while still an AutoIt newbie, because after 6 months I will not be able to see what I see clearly now as a newcomer.  So as an experienced VB6/VBA programmer, I dug right in to AutoIt by utilizing all the resources listed on my OP of this thread and then started writing code. In doing so, I documented the most important issues, questions and answers as they arose in a real time newbie experience. That's what I'm now calling my Quick Reference Guide. It does not teach how to program in AutoIt. It's a reference on how to use the most crucial features of SciTE, how to create code that complies with standards of the AutoIt community, and points out the major differences between VB6 coding and AutoIt coding. It also helps to fill in some of the gaps in info not provided for by the main AutoIt info resources.

I hope that better explains it. Thank you for the feedback and suggestions.

--pete--

Edited December 2, 2016 by PeteF

[PeteF]

3 hours ago, iamtheky said:

If you build something that would have helped you, chances are it would help someone else.  Opining will most likely bring far more counterpoints than support, because we are trained to come to these forums find problems and fix things.

To my way of thinking, counterpoints can be a good thing. As long as everyone has good intentions and act professionally, the end result is usually good in that we all benefit in some way or another. I always welcome constructive criticism.    Thank you for the encouragement.

[232showtime]

On 12/1/2016 at 0:16 PM, PeteF said:

The AutoIt Help file is acceptable, but so far, it often leaves me with more questions that could probably be filled in with a well written book

for this matter Im googling all the specific words related to my codes, and if I am still stuck with my code, I post the question together with my script, here in AutoIt Forum.

[JLogan3o13]

On 12/1/2016 at 4:16 AM, PeteF said:

The AutoIt Help file is acceptable, but so far, it often leaves me with more questions that could probably be filled in with a well written book.

Personally, if and when you find these instances, I would suggest making it known in the community. There are several threads that are centered on improving the help file; if you find something is lacking and point it out, someone can get it fixed so others are not similarly confused.

[czardas]

Regarding the first question about underscore being used in the naming of functions. Underscore is used for current functions within a UDF library by convention. Double underscore is used for internal functions within a UDF library. I'm not aware of any particular nomenclature conventions for functions outside of this definition, although some may have a different view on this matter. I personally think it's preferable to name functions which do not belong to a UDF differently, so as to easily tell them apart. I have now stopped prefixing underscore to function names in my main code, or for scripts created on the fly; with the option of adding it later if (and when) I decide to include the function in a UDF.

Edited December 12, 2016 by czardas

[iamtheky]

i think that differentiating between a library and a User Defined Function would also be helpful  

[czardas]

I totally agree: I think nomenclature should be clear, but without being overly verbose. I don't believe one set of rules can cover all bases. The important things to contemplate are clarity and consistency.

Edited December 12, 2016 by czardas

[PeteF]

On 12/12/2016 at 9:04 AM, JLogan3o13 said:

Personally, if and when you find these instances, I would suggest making it known in the community. There are several threads that are centered on improving the help file; if you find something is lacking and point it out, someone can get it fixed so others are not similarly confused.

Being brand new to the AutoIt community, I was reluctant to offer suggestions or critique until I got more familiar with the entire system and the community too.

So far, as I'm writing my first few programs, I begin with the AutoIt/SciTE HELP system which is quite good. After that, I spend a good deal of time searching the AutoIt forum and googling topics until I find the answer. So far, so good. I'm finding all my answers but it's very time consuming.

As I develop my first few AutoIt programs, I'm documenting and organizing all those answers to a brief reference type document, that I refer to as my AutoIt Quick Reference Guide. So far my AutoIt Quick Reference Guide is about 10 pages and covers most of what an experienced VB6 programmer would need to know to get up to speed quickly to develop a complete program using the AutoIt HELP system. I'm talking about an intermediate level program involving multiple forms & functions, file read/writes ops, command line parameters, use of the System Tray, controlling other Windows programs, debugging, using best coding practices, etc. It's not the typical beginners guide on how to program. I tried watching some of those AutoIt tutorials, but it was a bit frustrating. I kept fast forwarding them saying out loud; "I already know how to program, just tell me what's different or unique to AutoIt"'

So I began writing the quick ref guide mainly for myself and now I'm refining it for use by other experienced programmers who are brand new to AutoIt. I have not seen anything like it in all my searching for help to date.  I believe it will be a valuable resource to the community when it's completed. It will be my contribution,

JLogan, any chance you could direct me to those one of those threads that are dealing with improvements to the AutoIt HELP system?

-pete-