Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

Discuss the future of the AutoHotkey language
SOTE
Posts: 181
Joined: 15 Jun 2015, 06:21

Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

30 Sep 2018, 00:20

After a discussion with a friend, an interesting issue resulted. Is AutoHotkey Version 2 something that experienced or trained programmers find comforting, at the expensive of beginner and casual programmers? Let's look at various syntax. For example, String Replace (StrReplace() / StringReplace). I'm wondering if experienced or high level programmers forget what it's like to start out and not know programming.

Which is more easily readable and understandable? Arguably, Version 1 syntax is more easily understood.

The word StringReplace changed into StrReplace, then adding in "Haystack" can be confusing. So maybe there needs to be clarification about the syntax for version 2, when you no longer have the syntax of StringReplace and just StrReplace. And this goes for other such similar syntax changes.

Version 2 syntax-

Code: Select all

 ReplacedStr := StrReplace(Haystack, SearchText [, ReplaceText, OutputVarCount, Limit := -1])
Version 1 syntax-

Code: Select all

StringReplace, OutputVar, InputVar, SearchText [, ReplaceText, ReplaceAll]
I didn't realize this was even an issue, because even though I'm a casual user, I had become familiar with AutoHotkey over many months so the change in syntax wasn't so bothersome. However, when introducing the language to a friend who is a non-programmer, these "strange" syntax abbreviations and readability immediately became an issue for understanding.

Maybe part of this "confusion" can be alleviated in the help document, if it's felt that abbreviated wording must be used as keywords, by having the whole word String Replace at the top.

So a keyword lookup would look like
StrReplace (short for String Replace)
Last edited by SOTE on 01 Oct 2018, 01:34, edited 1 time in total.
User avatar
nnnik
Posts: 3453
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

30 Sep 2018, 02:01

Learning the syntax is a gradual process. While at the very begninning commands may be useful, you then have to completely relearn AutoHotkey when you switch to expressions.
Mayne people stop before that and thats neither good for us nor for them. So we decided to remove that hurdle.
Recommends AHK Studio
lexikos
Posts: 6201
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

30 Sep 2018, 05:15

I'm not sure this is really a "new" topic.
Arguably, Version 1 syntax is more easily understood.
So you say, but haven't actually posed an argument as I see it. That is just subjective opinion. Many others have done the same, with very few giving a plausible explanation.

The legacy syntax might seem easier when all you do is call for some action with some literal keystrokes, window titles, etc, but anything more complex (and every new user comes across this very soon) requires learning new symbols - even before you get to expressions, with a new set of rules. What's worse is that the symbols aren't used consistently.

Legacy syntax does not put quote marks around plain text, but as a result requires markers around variables. Even just considering this much, I don't believe it is easier, except maybe for the absolute beginner before they do anything useful. But then this cascades into a whole lot of inconsistencies, and imposes limitations that seemingly are only solved by having a whole new set of rules that supersede the legacy syntax.

Learning to put literal text in quote marks is a very simple step, and trying to avoid it only complicates matters and makes things worse in the long run. The quoting convention should be fairly familiar to anyone who is literate, in English at least - quoting literal text in a program is like quoting anywhere else.

So I suppose that what I'm saying is that no, v1 syntax is not more easily understood - as a whole. And it certainly is not easier to learn.
The word StringReplace changed into StrReplace, then adding in "Haystack" can be confusing.
Documentation changes (including parameter names) can be submitted via GitHub or suggested in the forums. However, I don't really get your point.
However, when introducing the language to a friend who is a non-programmer, these "strange" syntax abbreviations and readability immediately became an issue for understanding.
I don't know about others (you referred to abbreviations in the plural) but Str is a very common abbreviation. That might not help users totally new to programming or scripting of any kind, but it should also be easy to pick up by just looking at the description of each function.

Learning programming of any kind requires some work. No one is going to just pick it up effortlessly and immediately.
User avatar
jeeswg
Posts: 5265
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

30 Sep 2018, 05:48

- I am *very* sympathetic to these kinds of concerns. I always ask myself re. AHK v2, 'is AutoHotkey still easy'.
- I think that AHK v2 will be less confusing for newbies.
- The key point about AHK v2 is that the new syntax is a subset of the old syntax. It's generally replacing two ways of doing things, with one way of doing things, removing ambiguity.
- I remember every difficulty I've had with AutoHotkey, and virtually every point has been addressed, with the situation simplified.

FUNCTION NAMING

- 'StringReplace' to 'StrReplace' is hardly an issue.
- Shorter function names are easier to type.
- Narrower lines are easier to read.
- (I am somewhat sympathetic to the argument for fuller function/method names. IMO Java takes this too far, with ludicrously long method names e.g. lastIndexOf/toUnsignedString/equalsIgnoreCase. By contrast, C/C++ has some function names that are short but cryptic e.g. stoi. I think that 'Str' is readable yet short.)

PARAMETER NAMING

- I regard StrReplace as the most difficult function to find good parameter names for.
- I.e. this is not specifically an AHK v2 issue.
- There are 4 key parameters.
- The terms 'old text', 'new text', 'search(ed) text' and 'replace(d) text' are ambiguous.
- However, the terms 'needle' and 'haystack' are unambiguous, from the phrase: (like looking for) a needle in a haystack.
- Possibilities:
NewStr: after/new text, output
Haystack: before/old text, input
SearchText: before/old text, needle, 'find what'
ReplaceText: after/new text, 'replace with'

COMMAND V. FUNCTION SYNTAX

Code: Select all

Cmd ReturnValue, Arg1, Arg2, Arg3
ReturnValue := Func(Arg1, Arg2, Arg3)
- The function syntax already existed in AHK v1. So you already needed to be able to understand it.
- I was familiar with it from Excel sheet functions. To me, when I started, commands seemed like the oddity.
Excel SUBSTITUTE Function
https://www.excelfunctions.net/excel-su ... ction.html
- I learnt AutoIt before AutoHotkey, and found the function syntax perfectly straightforward.
- A further issue with the AHK v1 command-style parameters is escaping characters like spaces/tabs/commas/percent signs, this gets messy fast and affects readability.
- With AHK v1 command parameters, I could never remember which one was input, which one was output. The return value (output) is always clear with functions.

A_RESULT

- If AutoHotkey keeps command syntax, and introduces A_Result, you still have something quite simple:

Code: Select all

StringReplace NewStr, Haystack, %SearchTextVar%, %ReplaceTextVar%
StrReplace Haystack, SearchTextVar, ReplaceTextVar
NewStr := A_Result

StringReplace NewStr, Haystack, SearchTextLit, ReplaceTextLit
StrReplace Haystack, "SearchTextLit", "ReplaceTextLit"
NewStr := A_Result
IN GENERAL

- In terms of making things easy. IMO a difficult language with lots of examples, is easier than an easy language with few to no examples.
- So, for me, the focus should be on adding copious examples to the documentation, and on tutorials, particularly for the basic functions. (I can think of InStr, StrReplace, SubStr and Format. I'll do a full read-through of the documentation at some point.)
- I've recently completed matching beginner tutorials for C++/Java/Python, which I want to tidy a bit, and I'll be doing one for AutoHotkey presently.
- (Doing tutorials in other languages helped to make clear what experts from other languages might want. There's a danger of writing a tutorial based on the nature of the language, or on what can be done easily in the language, rather than based directly on what people want. It also reminded me of how newbies feel encountering a new language.)

- For me, the one thing that complicates a language is having to specify/convert/'cast' types, e.g. when defining variables, concatenating variables (in an expression) and (specifying parameters when) defining functions. It complicates everything and obscures the real code. This is why I find Python and AutoHotkey easy, and other, type-based, languages, difficult. This issue alone. In C++/Java, half the code deals with types.
guest3456
Posts: 2431
Joined: 09 Oct 2013, 10:31

Re: Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

30 Sep 2018, 19:22

if users find v2 too difficult, they can always continue to use v1

iseahound
Posts: 321
Joined: 13 Aug 2016, 21:04
GitHub: iseahound

Re: Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

30 Sep 2018, 20:02

Hey, this is very interesting because AutoHotkey is an automation based language. The key point about automation is that many actions are effectual, meaning that they may be non-deterministic, change state, and create effects. Many commands in v1 use command syntax to express this feeling such as the Run command, where depending on whether or not an executable is in the PATH will do the action or just fail. Click, X, Y again is an effect, since depending on what window is currently on the screen, will have a different outcome.

For commands with an OutputVar, function syntax is more natural. However, I think that v2 should accommodate both types of syntax to make it easier for beginning users, which make up the vast majority of our community.
SOTE
Posts: 181
Joined: 15 Jun 2015, 06:21

Re: Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

01 Oct 2018, 02:10

Hey, this is very interesting because AutoHotkey is an automation based language. The key point about automation is that many actions are effectual, meaning that they may be non-deterministic, change state, and create effects. Many commands in v1 use command syntax to express this feeling such as the Run command, where depending on whether or not an executable is in the PATH will do the action or just fail. Click, X, Y again is an effect, since depending on what window is currently on the screen, will have a different outcome.

For commands with an OutputVar, function syntax is more natural. However, I think that v2 should accommodate both types of syntax to make it easier for beginning users, which make up the vast majority of our community.
iseahound, I think you are understanding the spirit of what I mean. Because AutoHotkey has an automation base, there is likely more of an expectation of 1 to 1, cause and effect. Click this, than do this. See this, than do that. And AutoHotkey has a syntax that more strongly reflects this, arguably making it much easier for non-programmers to pick up and use much more quickly than other programming languages.

Code: Select all

StringSplit, OutputArray, InputVar [, Delimiters, OmitChars]
The version 1 syntax above has a great level of readability, for non-programmers and is closer to normal English. The more that a scripting language begins to drift away from more easily understood languge, possibly the more difficult it can be to understand. So when confronted with version 2 syntax, like below, it's more likely to produce head scratching.

Code: Select all

Array := StrSplit(String [, Delimiters, OmitChars, MaxParts := -1])
It's not to say that a learning curve can be eliminated or that the language can always or easily describe what is complex, but rather how easy it is to understand a language can effect outcomes and use.
Last edited by SOTE on 01 Oct 2018, 02:21, edited 3 times in total.
SOTE
Posts: 181
Joined: 15 Jun 2015, 06:21

Re: Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

01 Oct 2018, 02:11

I'm not sure this is really a "new" topic.
Arguably, Version 1 syntax is more easily understood.
So you say, but haven't actually posed an argument as I see it. That is just subjective opinion. Many others have done the same, with very few giving a plausible explanation.

The legacy syntax might seem easier when all you do is call for some action with some literal keystrokes, window titles, etc, but anything more complex (and every new user comes across this very soon) requires learning new symbols - even before you get to expressions, with a new set of rules. What's worse is that the symbols aren't used consistently.

Legacy syntax does not put quote marks around plain text, but as a result requires markers around variables. Even just considering this much, I don't believe it is easier, except maybe for the absolute beginner before they do anything useful. But then this cascades into a whole lot of inconsistencies, and imposes limitations that seemingly are only solved by having a whole new set of rules that supersede the legacy syntax.

Learning to put literal text in quote marks is a very simple step, and trying to avoid it only complicates matters and makes things worse in the long run. The quoting convention should be fairly familiar to anyone who is literate, in English at least - quoting literal text in a program is like quoting anywhere else.

So I suppose that what I'm saying is that no, v1 syntax is not more easily understood - as a whole. And it certainly is not easier to learn.
The word StringReplace changed into StrReplace, then adding in "Haystack" can be confusing.
Documentation changes (including parameter names) can be submitted via GitHub or suggested in the forums. However, I don't really get your point.
However, when introducing the language to a friend who is a non-programmer, these "strange" syntax abbreviations and readability immediately became an issue for understanding.
I don't know about others (you referred to abbreviations in the plural) but Str is a very common abbreviation. That might not help users totally new to programming or scripting of any kind, but it should also be easy to pick up by just looking at the description of each function.

Learning programming of any kind requires some work. No one is going to just pick it up effortlessly and immediately.
lexikos, don't get me wrong, I think what you have done is fantastic (to include expanding the capabilities of AutoHotkey) and I'm a fan. And you are right, such observations are quite subjective, to include that version 1 syntax has plenty of flaws with it. However, the point was to mention it, and maybe look again at the perspective of non-programmers and new people. And I also agree that the help documentation and GitHub submissions can mitigate such issues somewhat. Personally, I find the short examples and programming snippets do the most to help.
Last edited by SOTE on 01 Oct 2018, 02:29, edited 2 times in total.
lexikos
Posts: 6201
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

01 Oct 2018, 04:28

However, the point was to mention it, and maybe look again at the perspective of non-programmers and new people.
So you've mentioned it, and nothing has changed. Unless someone can offer a new perspective, regardless of their level of experience, this is futile.

"Non-programmers and new people" are not the right people to be designing a language, even for "non-programmers and new people", and the rest of us cannot pretend to be new. That aside, a language that only non-programmers would use will have no developers, and will go nowhere.
lexikos
Posts: 6201
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

01 Oct 2018, 05:58

Apparently I missed some posts. I also got a server error but apparently posted twice (which is twice more than I thought). I've deleted the duplicate.

I believe that the v1 syntax being "easier" to read for beginners or closer to English is only superficial, if even true, and offers no real benefit.
User avatar
jeeswg
Posts: 5265
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

03 Oct 2018, 21:12

- @SOTE: I think on balance AHK v2 is easier:

Code: Select all

;AHK v1:
Cmd %var%
Cmd string
Cmd % 1 + 1

;AHK v2:
Cmd var
Cmd "string"
Cmd 1 + 1

;AHK v1/v2:
Func(var)
Func("string")
Func(1 + 1)
- Your argument seems to be:

Code: Select all

;easy:
Cmd Output, Input

;hard:
Output := Func(Input)
- This is the only bit of syntax you've really mentioned.
- I can appreciate that the first one arguably does look a little less daunting to a newbie.
- However, there's still a learning curve for the first one.
- And, the second one, if you're honest, is pretty straightforward.
- (There's the which is input/output disadvantage for commands, which I mentioned before.)
- (Also, functions are necessary in AHK e.g. for expressions/one-liners, and are commonplace elsewhere e.g. Excel. Better to introduce it well, than to delay introducing it.)

- If you used command-style notation here, would it really make things easier?
- Whether commands or functions were used, I think the key is a good example.

Code: Select all

;==================================================

;replace 'abc' with '___'

vText := "abcdef"
vTextNew := StrReplace(vText, "abc", "___")
MsgBox(vText "`r`n" vTextNew)

;==================================================

;split a string to create a (linear) array

vText := "abc,def,ghi"
oArray := StrSplit(vText, ",")
MsgBox(vText "`r`n" oArray[1] "`r`n" oArray[2] "`r`n" oArray[3])

;==================================================

;count the items in an array

MsgBox(oArray.Count())

;==================================================
- How many languages use commands as in AHK v1?
roysubs
Posts: 105
Joined: 29 Sep 2018, 16:37

Re: Will AutoHotkey v2 Syntax Be More Confusing For Newbies?

06 Oct 2018, 13:00

Everything I've seen of v2 is massively better. I found v1 *extremely* confusing when I started. v2 will be easier to get into with a more sensible syntax.
I'm very excited for AutoHotkey v2 to be finalised soon!

Return to “AutoHotkey v2 Development”

Who is online

Users browsing this forum: No registered users and 4 guests