your personal AutoHotkey style guide

Talk about anything
User avatar
jeeswg
Posts: 5271
Joined: 19 Dec 2016, 01:58
Location: UK

your personal AutoHotkey style guide

11 Apr 2018, 15:53

- This is my personal AutoHotkey style guide.
- Please share your personal AutoHotkey style guide.
- I've included all of the choices I could think of. There may be others that I missed out, so do please include examples of other choices (other points of debate).
- People are welcome to post general posts, but please try to keep your complete (up-to-date) style guide within one post. Thank you all.

Code: Select all

;YES
;comment
;NO
; comment

;Indentation style - Wikipedia
;https://en.wikipedia.org/wiki/Indentation_style

;YES (Allman style)
Loop, 3
{
	MsgBox
	Loop, 3
	{
		InputBox, vInput
	}
}
;NO (K&R: one true brace)
Loop, 3 {
	MsgBox
	Loop, 3 {
		InputBox, vInput
	}
}

;YES
if (var1 = var2)
;NO
if ( var1 = var2 )

;YES
oArray := ["a", "b", "c"]
;NO
oArray := ["a","b","c"]

;YES
DllCall("MessageBox", Ptr,0, Str,"text", Str,"title", UInt,0)
;NO
DllCall("MessageBox", "Ptr", 0, "Str", "text", "Str", "title", "UInt", 0)

;YES
MsgBox, % var "text" var var "text" "text" var "text"
;NO
MsgBox, % var . "text" . var . var . "text" . "text" . var . "text"

;YES (initial commas)
Loop, Parse, vText, `n, `r
;NO (no initial commas)
Loop Parse, vText, `n, `r

;YES (initial commas)
MouseGetPos, vCurX, vCurY, hWnd, vCtlClassNN
MouseGetPos,,, hWnd, vCtlClassNN
;NO (no initial commas)
MouseGetPos vCurX, vCurY, hWnd, vCtlClassNN
MouseGetPos ,, hWnd, vCtlClassNN

;YES
vText
oArray
;NO
text
array

;YES
if !(var1 = var2)
;NO
if not (var1 = var2)

;YES
if (var1 && var2)
if (var1 || var2)
;NO
if (var1 AND var2)
if (var1 OR var2)

;OBVIOUSLY YES
var := "text"
var1 := var2
;OBVIOUSLY NO (NOTE: NOT AVAILABLE IN AHK V2)
var = text
var1 = %var2%

;YES
vText := "line 1`r`n" "line 2`r`n" "line 3"
;NO (the 'n' combines with the string, bad for spellchecking)
vText := "line 1`r`nline 2`r`nline 3"

;YES
vText := A_Space A_Space
;NO (never have multiple consecutive spaces)
vText := "  "

;YES (indentation of 1 tab)
if (var1 = var2)
	MsgBox
;NO (indentation of 4 spaces)
if (var1 = var2)
    MsgBox

;AMBIGUOUS CASES ...

;YES
if (var1 = var2)
	MsgBox
;IT'S OK (UNNECESSARY CURLY BRACES)
if (var1 = var2)
{
	MsgBox
}

;IT DEPENDS
var := 1 + 1
;IT DEPENDS
var := 1+1
[EDIT:] Further points are listed here:
your personal AutoHotkey style guide - Page 2 - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 06#p217206

Links:
v2 docs contribution questions - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 55#p221055
AutoHotkey style guide - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 17&t=14089
GitHub - aviaryan/Ahk-Best-Practices: [WIP] AutoHotkey Best Practices
https://github.com/aviaryan/Ahk-Best-Practices
Coding Style Guidelines - Programming - AutoHotkey Community
https://autohotkey.com/board/topic/8205 ... uidelines/
Codestyle: implicit and explicit concatenation - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 17&t=46983
Syntax and naming conventions? - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 17&t=44183
Last edited by jeeswg on 03 Jun 2018, 22:51, edited 4 times in total.
swagfag
Posts: 1371
Joined: 11 Jan 2017, 17:59

Re: your personal AutoHotkey style guide

11 Apr 2018, 17:49

Code: Select all

;NO, occasionally on inline comments
;comment
;YES, autoformatted by editor
; comment

;Indentation style - Wikipedia
;https://en.wikipedia.org/wiki/Indentation_style

;NO (Allman style)
Loop, 3
{
	MsgBox
	Loop, 3
	{
		InputBox, vInput
	}
}
;YES (K&R: one true brace)
Loop, 3 {
	MsgBox
	Loop, 3 {
		InputBox, vInput
	}
}

;YES
if (var1 = var2)
;NO
if ( var1 = var2 )

;YES
oArray := ["a", "b", "c"]
;NO
oArray := ["a","b","c"]

;NO
DllCall("MessageBox", Ptr,0, Str,"text", Str,"title", UInt,0)
;YES
DllCall("MessageBox", "Ptr", 0, "Str", "text", "Str", "title", "UInt", 0)
; altenatively, where applicable
DllCall("MessageBox"
	, "Ptr", 0
	, "Str", "text"
	, "Str", "title"
	, "UInt", 0)

;NO
MsgBox, % var "text" var var "text" "text" var "text"
;YES
MsgBox, % var . "text" . var . var . "text" . "text" . var . "text"
; altenatively, where applicable
MsgBox, % var . "text" . var . var
	 . "text" . "text" . var 
	 . "text"

;YES (initial commas)
Loop, Parse, vText, `n, `r
;NO (no initial commas)
Loop Parse, vText, `n, `r

;YES (initial commas)
MouseGetPos, vCurX, vCurY, hWnd, vCtlClassNN
MouseGetPos,,, hWnd, vCtlClassNN
;NO (no initial commas)
MouseGetPos vCurX, vCurY, hWnd, vCtlClassNN
MouseGetPos ,, hWnd, vCtlClassNN

;NO, adjHungarian nNotation auxCan vGo vDie
vText
oArray
;YES
text
array

;YES
if !(var1 = var2)
;NO
if not (var1 = var2)

;YES
if (var1 && var2)
if (var1 || var2)
;NO
if (var1 AND var2)
if (var1 OR var2)

;OBVIOUSLY YES
var := "text"
var1 := var2
;OBVIOUSLY NO (NOTE: NOT AVAILABLE IN AHK V2)
var = text
var1 = %var2%

;NO
vText := "line 1`r`n" "line 2`r`n" "line 3"
;if im lazy(i dont have spellcheck enabled) and/or most of the time
vText := "line 1`r`nline 2`r`nline 3"
;utmost pedantry
vText := "line 1"
	. "`r`n" . "line 2"
	. "`r`n" . "line 3"

;cant recall the last time i had to put 2 consecutive spaces
;??
vText := A_Space A_Space
;??
vText := "  "

;YES (indentation of 1 tab)
if (var1 = var2)
	MsgBox
;NO (indentation of 4 spaces)
if (var1 = var2)
    MsgBox

;AMBIGUOUS CASES ...

;NO
if (var1 = var2)
	MsgBox
;NO
if (var1 = var2)
{
	MsgBox
}
;YES(braces arent unnecessary, they guard against errors)
if (var1 = var2) {
	MsgBox
}

;YES
var := 1 + 1
;NO
var := 1+1
User avatar
nnnik
Posts: 3457
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: your personal AutoHotkey style guide

12 Apr 2018, 00:08

Code: Select all

;DUNNO
;comment
;MAYBE
; comment
;IDK
;~ comment

;Indentation style - Wikipedia
;https://en.wikipedia.org/wiki/Indentation_style

;USED TO - I get influenced by other languages I have to learn rather frequently
Loop, 3
{
	MsgBox
	Loop, 3
	{
		InputBox, vInput
	}
}
;LATELY - I got used to this but it migh change again
Loop, 3 {
	MsgBox
	Loop, 3 {
		InputBox, vInput
	}
}

;NO
if (var1 = var2)
;YES
if ( var1 = var2 )

;NO
oArray := ["a", "b", "c"]
;NO
oArray := ["a","b","c"]
;YES
oArray := [ "a", "b", "c" ]

;NO
DllCall("MessageBox", Ptr,0, Str,"text", Str,"title", UInt,0)
;NO
DllCall("MessageBox", "Ptr", 0, "Str", "text", "Str", "title", "UInt", 0)
;NO - never multiple lines are reserved for code structural syntax elements ( e.g. a function or a loop )
DllCall("MessageBox"
	, "Ptr", 0
	, "Str", "text"
	, "Str", "title"
	, "UInt", 0)
;YES
DllCall( "MessageBox", "Ptr", 0, "Str", "text", "Str", "title", "UInt", 0 )

;NO
MsgBox, % var "text" var var "text" "text" var "text"
;YES
MsgBox, % var . "text" . var . var . "text" . "text" . var . "text"
;NO - never multiple lines are reserved for code structural syntax elements ( e.g. a function or a loop )
MsgBox, % var . "text" . var . var
	 . "text" . "text" . var 
	 . "text"

;50% (initial commas)
Loop, Parse, vText, `n, `r
;50% (no initial commas)
Loop Parse, vText, `n, `r

;50%
MouseGetPos, vCurX, vCurY, hWnd, vCtlClassNN
MouseGetPos,,, hWnd, vCtlClassNN
;50%
MouseGetPos vCurX, vCurY, hWnd, vCtlClassNN
MouseGetPos ,, hWnd, vCtlClassNN

;NO, adjHungarian nNotation auxCan vGo vDie - +1
vText
oArray
;NO
text
array
;YES
camelCaseForVars
CamelCaseForClasses

;YES
if !(var1 = var2)
;NO
if not (var1 = var2)

;YES
if (var1 && var2)
if (var1 || var2)
;NO
if (var1 AND var2)
if (var1 OR var2)

;OBVIOUSLY YES
var := "text"
var1 := var2
;OBVIOUSLY NO (NOTE: NOT AVAILABLE IN AHK V2)
var = text
var1 = %var2%

;NO
vText := "line 1`r`n" "line 2`r`n" "line 3"
;YES - why would you make a single string uneccessary long - also why `r`n instead of just `n?
vText := "line 1`r`nline 2`r`nline 3"
;utmost pedantry
vText := "line 1"
	. "`r`n" . "line 2"
	. "`r`n" . "line 3"

;cant recall the last time i had to put 2 consecutive spaces - me neither
;??
vText := A_Space A_Space
;??
vText := "  "

;YES (indentation of 1 tab)
if (var1 = var2)
	MsgBox
;NO (indentation of 4 spaces)
if (var1 = var2)
    MsgBox

;AMBIGUOUS CASES ...

;YES - but if Im sure that I debug this code regularily 
if (var1 = var2)
	MsgBox
;NO
if (var1 = var2)
{
	MsgBox
}
;YES - I leave this braces
if (var1 = var2) {
	MsgBox
}

;YES
var := 1 + 1
;NO
var := 1+1
Recommends AHK Studio
User avatar
jeeswg
Posts: 5271
Joined: 19 Dec 2016, 01:58
Location: UK

Re: your personal AutoHotkey style guide

12 Apr 2018, 02:19

- Great feedback so far, especially re. Hungarian notation, thanks.
- I don't think that noting the exact type is that important, but distinguishing between variables/objects is useful.
- Here's another benefit:

Code: Select all

;let's say that you've defined PID, but what if you wanted to define PID2 also, which 'PID' to change?
WinGet, PID, PID, A
WinGet, vPID, PID, A
Helgef
Posts: 3226
Joined: 17 Jul 2016, 01:02
Contact:

Re: your personal AutoHotkey style guide

12 Apr 2018, 03:19

Hello, fun topic :wave:.
My style is dynamic :D. For me, commenting my code is the most important thing.

Code: Select all

DllCall("MessageBox", Ptr,0, Str,"text", Str,"title", UInt,0)) ; Best case, creates three unnecessary blank variables.
That should not be allowed, it is horrible.
...lots of spaces...
It make your code very nice to look at, I couldn't cope putting so much space so consistently though. I put extra space when I feel it helps me.

Code: Select all

;IT DEPENDS
var := 1 + 1
;IT DEPENDS
var := 1+1
Indeed, it depends on the surroundings, if it helps me, I'll put extra spaces.
vVar oArray
Those prefixes are cumbersome for me to look at. Do not get me wrong, readability is subjective, I admire your consistency with them, and respect your style.

Cheers.
User avatar
jeeswg
Posts: 5271
Joined: 19 Dec 2016, 01:58
Location: UK

Re: your personal AutoHotkey style guide

12 Apr 2018, 04:47

- @Helgef: For DllCall, the optional double quotes, that I've omitted, would make the line very wide, and also harder to read.
- Also, sometimes people nest a DllCall line within a DllCall line, using the double quotes makes this less feasible.
- Do you think that that style actually affects performance? (By creating variables called Ptr/Str/UInt.) I would have thought that AutoHotkey was/could be optimised to handle it.
- By using the v and o prefixes it can make certain aspects of parsing much easier. E.g. I have a script that looks for words starting with lower-case o/v, (or 'A_',) and then I can easily rename variables by overwriting the comma-separated list presented in an InputBox.
- Thanks for your kind words.
User avatar
jeeswg
Posts: 5271
Joined: 19 Dec 2016, 01:58
Location: UK

Re: your personal AutoHotkey style guide

12 Apr 2018, 04:50

Three notation quandaries that I faced, all now with a solution.

notation: parameter could be a variable or an object - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=43090
[solution: choose 'o' or 'v' as the default, do an IsObject() check at the start of the function, and create a new 'o'/'v' variable if needed][also: add a comment above the function explaining that the parameter can accept a string or an object]

notation: parameter that specifies delimiters/separators - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=43273
[solution: a delimiter/separator parameter could accept one string or a linear array, just like StrSplit][it's often a sensible thing to do, to have a separate delimiter/september parameter (instead of it being one item in a comma-separated list as in the Sort command)]

notation: objects: key names to avoid clashes with methods/properties - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=43595
[solution: prefix key names with 'z']
User avatar
nnnik
Posts: 3457
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: your personal AutoHotkey style guide

12 Apr 2018, 04:53

Helgef
Thanks :)
AHK studio does most of it for me and in the cases I have to do it myself it's already in my muscle memory.

jeeswg
As far as I know variables point to objects so it's either a variable containing something different than an object or a variable containing an object reference.
I dont quite understand why you put the difference between v and o - I can see that you want to denote types but there are probably more different object types than you can form with 3 letters in the alphabet.
So I think that at most is a futile attempt - while I think that the intention behind it is useful.
Recommends AHK Studio
guest3456
Posts: 2433
Joined: 09 Oct 2013, 10:31

Re: your personal AutoHotkey style guide

12 Apr 2018, 09:26

btw: of course spaces over tabs. thats not even a question. ;)

most of this is personal preference, but some comments:

Code: Select all

;YES
DllCall("MessageBox", Ptr,0, Str,"text", Str,"title", UInt,0)
;NO
DllCall("MessageBox", "Ptr", 0, "Str", "text", "Str", "title", "UInt", 0)
I'm not sure if this is even legal AHK code. I'm pretty sure those type parameters are strings. I've only ever seen them as strings in the docs. While it may work, I think its bad practice. Your spacing is interesting though.

Code: Select all

;YES
vText
oArray
;NO
text
array
not a fan of this at all. it makes the code way less readable and adds negligible information. i would only do this on occasion if i thought it was necessary. otherwise i'd spend more time just naming the variables properly so that they are as descriptive as possible. this is not trivial. its important.
- Great feedback so far, especially re. Hungarian notation, thanks.
- I don't think that noting the exact type is that important, but distinguishing between variables/objects is useful.
- Here's another benefit:

Code: Select all

;let's say that you've defined PID, but what if you wanted to define PID2 also, which 'PID' to change?
WinGet, PID, PID, A
WinGet, vPID, PID, A
so in this example, just naming it "PID" or "vPID" are both awful. better would be something like "active_PID". naming variables is one of the most overlooked things and the first indicator of a sloppy programmer.

your code should self-document itself as much as possible. sometimes i will go to the extreme and even create a separate variable to describe the if-condition if its longish in order to make the code more expressive:

Code: Select all

if (
    fruit.sweet === true &&
    fruit.colors.some(color => color === 'yellow')
) {
    alert('do your stuff')
    return 'is banana'
}

;vs

const isSweet = fruit.sweet === true
const isYellow = fruit.colors.some(color => color === 'yellow')
const isBanana = isYellow && isSweet

if (isBanana) {
    alert('do your stuff')
    return 'is banana'
}

User avatar
jeeswg
Posts: 5271
Joined: 19 Dec 2016, 01:58
Location: UK

Re: your personal AutoHotkey style guide

12 Apr 2018, 14:20

- Re. DllCall and the type parameters using double quotes or not:
DllCall
https://autohotkey.com/docs/commands/DllCall.htm
Note: When specifying an argument type or return type that does not contain a space or asterisk, the quotes around it may be omitted. For example, Str can be used in place of "Str" and CDecl in place of "CDecl". In addition, the letter P may be used in place of asterisk to allow the quotes to be omitted there as well. For example: UIntP.
- @guest3456: I think I'd seen at different points, both: the double quotes for type parameters omitted, and, the parameters bunched into pairs, both of which I think help with readability. I would also bunch parameter pairs together when using the Object() function.
E.g. Object("k1","v1", "k2","v2", "k3","v3")
- Funnily enough I find that o/v really help with readability, it's immediate, you know that what you're looking is an object/variable and not something else.
- Do you also use active_hWnd / active_hwnd or something like it?
- [EDIT:] There is a potential problem with 'active_pid', it can be misleading since it is not guaranteed to correspond to the active PID. A function, ActivePID() / PIDActive(), with such a name, would make more sense.
User avatar
derz00
Posts: 497
Joined: 02 Feb 2016, 17:54
GitHub: derz00
Location: Middle of the round cube

Re: your personal AutoHotkey style guide

12 Apr 2018, 19:22

[EDIT:] There is a potential problem with 'active_pid', it can be misleading since it is not guaranteed to correspond to the active PID. A function, ActivePID() / PIDActive(), with such a name, would make more sense.
Hm? It is guaranteed--the 3rd parameter is "A" (which stands for "active"). What am I missing?

If the window parameter was "Untitled - Notepad" you would call the variable "notepad_pid". If I'm understanding guest3456, that's what he means by naming variables.
try it and see
...
User avatar
jeeswg
Posts: 5271
Joined: 19 Dec 2016, 01:58
Location: UK

Re: your personal AutoHotkey style guide

12 Apr 2018, 19:33

@derz00: Adding 'notepad_' would be fine, adding 'active_' could mislead someone not familiar with AutoHotkey. It's the same principle with: vNow := A_Now v. vDate := A_Now, vNow would only correctly correspond to now for one second, after that the variable name is misleading. Furthermore some variables in AutoHotkey, the 'A_' variables, magically update, e.g. A_Now, but vNow wouldn't.
User avatar
derz00
Posts: 497
Joined: 02 Feb 2016, 17:54
GitHub: derz00
Location: Middle of the round cube

Re: your personal AutoHotkey style guide

12 Apr 2018, 19:41

I'm not sure what this has to do with AutoHotkey. Maybe because it's the only language with a WinGet function?

And I also don't understand how clear and true description in naming variables can mislead someone. You asked for the PID of the active window, that's what you get, and until you have a better use for it, it's the active pid. That's all you know about that PID so far. That truth would change, of course, when the active window changes. But the original point was being more descriptive than simply "vPID". Whatever. Not very profound I guess.
try it and see
...
User avatar
jeeswg
Posts: 5271
Joined: 19 Dec 2016, 01:58
Location: UK

Re: your personal AutoHotkey style guide

12 Apr 2018, 19:57

I agree with guest3456's point, adding additional information to variable names is good, but for the reasons I stated, adding the word 'active' could be counterproductive, and even if it wasn't, the word is rarely helpful IMO, hence why I never use the word 'active' in any of my variable names.
guest3456
Posts: 2433
Joined: 09 Oct 2013, 10:31

Re: your personal AutoHotkey style guide

12 Apr 2018, 21:01

- Re. DllCall and the type parameters using double quotes or not:
DllCall
https://autohotkey.com/docs/commands/DllCall.htm
Note: When specifying an argument type or return type that does not contain a space or asterisk, the quotes around it may be omitted. For example, Str can be used in place of "Str" and CDecl in place of "CDecl". In addition, the letter P may be used in place of asterisk to allow the quotes to be omitted there as well. For example: UIntP.
- @guest3456: I think I'd seen at different points, both: the double quotes for type parameters omitted
good catch. not sure if i prefer it or not. its bad from a syntax standpoint: the user should be thinking those are variables being passed instead of types for the next params.
[EDIT:] There is a potential problem with 'active_pid', it can be misleading since it is not guaranteed to correspond to the active PID. A function, ActivePID() / PIDActive(), with such a name, would make more sense.
Hm? It is guaranteed--the 3rd parameter is "A" (which stands for "active"). What am I missing?

If the window parameter was "Untitled - Notepad" you would call the variable "notepad_pid". If I'm understanding guest3456, that's what he means by naming variables.
yes you understand exactly

john_c
Posts: 175
Joined: 05 May 2017, 13:19

Re: your personal AutoHotkey style guide

13 Apr 2018, 11:43

I think I'd seen at different points, both: the double quotes for type parameters omitted, and, the parameters bunched into pairs, both of which I think help with readability.
Very interestin thread :-)

What actually you mean by the words "I think I'd seen at different points, both"? (It's quite hard to understand probably because I'm not native English speaker).
User avatar
jeeswg
Posts: 5271
Joined: 19 Dec 2016, 01:58
Location: UK

Re: your personal AutoHotkey style guide

13 Apr 2018, 11:48

To rephrase:
I think I once saw a script where the double quotes were omitted.
I think I once saw a script where the parameters were paired up.
Did Google Translate give you the correct translation?
john_c
Posts: 175
Joined: 05 May 2017, 13:19

Re: your personal AutoHotkey style guide

13 Apr 2018, 12:54

...
Thanks.

Yes, Google Translate was quite close. There are 2 another small questions regarding your style guide, if it's not too boring to answer them:
  • "the 'n' combines with the string, bad for spellchecking" - as I understand, you mean the spellcheck inside text editor/IDE? So, it will be correctly spellchecked in one editor but incorrectly in another?
  • "Also, sometimes people nest a DllCall line within a DllCall line, using the double quotes makes this less feasible" - if I understand you correctly, you mean that with quotes it will be sometimes impossible? (I never worked with DllCalls before).
User avatar
jeeswg
Posts: 5271
Joined: 19 Dec 2016, 01:58
Location: UK

Re: your personal AutoHotkey style guide

13 Apr 2018, 14:36

- Re. spellchecking, I use a spellchecker script. If a spellchecker simply removes non-letters/non-numbers then `r`nword would become nword, which is not a valid word. I could just make it replace `n, before spellchecking.
- Doing "text`r`n" "text", instead of "text`r`ntext", may not really be necessary, I might have had some other reason.

- This is nesting: MyFunc(Arg1, Arg2, MyFunc2(), Arg4, Arg5), a function call within a function call.
- Here, additional double quotes and spaces make the second version longer. It's preferable to keep things shorter, otherwise to see the whole line you have to: break it up into two lines, or use word wrap, or not see the end of the line, or use a smaller font etc.

Code: Select all

vRet := !!DllCall("user32\DestroyIcon", Ptr,DllCall("user32\CopyIcon", Ptr,hIcon, Ptr))

vRet := !!DllCall("user32\DestroyIcon", "Ptr", DllCall("user32\CopyIcon", "Ptr", hIcon, "Ptr"))
john_c
Posts: 175
Joined: 05 May 2017, 13:19

Re: your personal AutoHotkey style guide

13 Apr 2018, 14:51

@jeeswg Now I understand. Thank you very much :-)

Return to “Offtopic”

Who is online

Users browsing this forum: No registered users and 17 guests