AutoHotkey style guide

Talk about anything
User avatar
Avi
Posts: 193
Joined: 30 Sep 2013, 09:51
Facebook: avi.aryan.ap
Google: +AviAryan
GitHub: aviaryan
Location: India
Contact:

AutoHotkey style guide

17 Feb 2016, 00:55

Hi. I was wondering if there is a code-style and best practices guide available for AutoHotkey . Something like https://github.com/airbnb/javascript
This would be very helpful for the community and will help maintain a certain code standard and consistency.
If there is not, let's create it on github/ahkscript .
Writes at Dev Letters

Clipjump Clipboard Manager : More Scripts (updated 2019)

Image
User avatar
Avi
Posts: 193
Joined: 30 Sep 2013, 09:51
Facebook: avi.aryan.ap
Google: +AviAryan
GitHub: aviaryan
Location: India
Contact:

Re: AutoHotkey style guide

17 Feb 2016, 01:20

Last edited by Avi on 20 Feb 2016, 00:48, edited 2 times in total.
Writes at Dev Letters

Clipjump Clipboard Manager : More Scripts (updated 2019)

Image
Coco
Posts: 771
Joined: 29 Sep 2013, 20:37
GitHub: cocobelgica

Re: AutoHotkey style guide

17 Feb 2016, 05:33

README.md wrote:

Code: Select all

; bad
s := "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Totam, minima!`n"
    . "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eum, eaque.`n"
    . "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Et, veniam."
; good
s = 
(
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Totam, minima!
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eum, eaque.
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Et, veniam.
)
Source: Strings
The issue with the latter approach(although it's easier to write/read) is that it is not future-proof, v2-compatible.
Perhaps:

Code: Select all

s :=  "
(
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Totam, minima!
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eum, eaque.
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Et, veniam.
)"
; OR
s :=
(
"Lorem ipsum dolor sit amet, consectetur adipisicing elit. Totam, minima!
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eum, eaque.
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Et, veniam."
)
Now another problem arises though, on v1.1, %some_variable% within the multi-line string will be treated literally, while on v2, it's a variable reference. I guess this one is already outside the styling guide topic.
User avatar
Blackholyman
Posts: 1272
Joined: 29 Sep 2013, 22:57
Facebook: socialjsz
Google: +Jszapp
Location: Denmark
Contact:

Re: AutoHotkey style guide

17 Feb 2016, 07:27

Great idea

I also made a post with some of my thoughts but it's very overall and does not really tell you how to style your code

Image
AutoHotkey Scripting Thoughts: Best Practices
Also check out:
[hr][/hr]The Monthly AutoHotkey Webinars

My Autohotkey Blog
:dance: [hr][/hr]
guest3456
Posts: 2528
Joined: 09 Oct 2013, 10:31

Re: AutoHotkey style guide

17 Feb 2016, 08:39

Avi wrote:Hi. I was wondering if there is a code-style and best practices guide available for AutoHotkey . Something like https://github.com/airbnb/javascript
This would be very helpful for the community and will help maintain a certain code standard and consistency.
If there is not, let's create it on github/ahkscript .
i think you're confused

"style guides" are written by individual organizations to be used for anyone who contributes to their codebase. you just randomly happened to pick one from AirBnB. now if you wanted to submit a pull request to that repo, they would expect you to follow their styling guide.

i'm sure you can find 100s of different style guides for javascript.
Avi wrote:I was bored and created the repository. :thumbup:
https://github.com/ahkscript/Ahk-Style-Guide
i appreciate the effort you're putting in, but like most of the repositories under the 'ahkscript' account, this doesn't belong as part of the org. i thought there was enough people clamoring in the past to remove all of those ridiculous repositories from the main org account and force the maintainers to stick them in this personal accounts. i guess it never happened

this should be your personal repo and your personal style guide, which can then possibly be linked from the awesome-ahk list, along with other style guides.

style guides are a personal preference thing, and you will never get agreement from the community, which is even another reason why this should be a personal repository rather than an organizational one

the only thing i agree with on your list is using proper case. tabs instead of spaces? please.

User avatar
tidbit
Posts: 1126
Joined: 29 Sep 2013, 17:15
Location: USA

Re: AutoHotkey style guide

17 Feb 2016, 10:32

tutorial section 8.4 covers Indentation basics:
https://autohotkey.com/docs/Tutorial.htm#s84

1.2 covers my recommendation for hotkeys (not remaps) to newbies. multi-line, not single line. to try and prevent some common confusion:
https://autohotkey.com/docs/Tutorial.htm#s12

Also, I much prefer camelCase (lowerUpperUpper) over ProperCase. and hate things_with_underscores
rawr. fear me.
*poke*
Is it December 21, 2012 yet?
User avatar
Avi
Posts: 193
Joined: 30 Sep 2013, 09:51
Facebook: avi.aryan.ap
Google: +AviAryan
GitHub: aviaryan
Location: India
Contact:

Re: AutoHotkey style guide

17 Feb 2016, 13:19

Coco wrote: The issue with the latter approach(although it's easier to write/read) is that it is not future-proof, v2-compatible.
Perhaps:

Code: Select all

s :=  "
(
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Totam, minima!
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eum, eaque.
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Et, veniam.
)"
; OR
s :=
(
"Lorem ipsum dolor sit amet, consectetur adipisicing elit. Totam, minima!
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eum, eaque.
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Et, veniam."
)
Now another problem arises though, on v1.1, %some_variable% within the multi-line string will be treated literally, while on v2, it's a variable reference. I guess this one is already outside the styling guide topic.
I agree. Just forgot about this syntax. btw, I am not able to do something like this with the 2nd syntax

Code: Select all

v = 4
s := "
(
test
123
)" . v . "
(
lol
123
)"
msgbox % s
Blackholyman wrote:Great idea

I also made a post with some of my thoughts but it's very overall and does not really tell you how to style your code

Image
AutoHotkey Scripting Thoughts: Best Practices
Thanks. Your contribution is very much appreciated.
guest3456 wrote: i think you're confused
"style guides" are written by individual organizations to be used for anyone who contributes to their codebase. you just randomly happened to pick one from AirBnB. now if you wanted to submit a pull request to that repo, they would expect you to follow their styling guide.
i'm sure you can find 100s of different style guides for javascript.
The aim here is to make a style guide that majority of the community would find useful, that most of the community agrees in. I am well aware that creating a full-proof, universal style-convention isn't possible; there will always be rules people won't like agreeing to, and they are free to skip them.
guest3456 wrote:tabs instead of spaces? please.

A GitHub issue ( https://github.com/ahkscript/Ahk-Style-Guide/issues ) can be created for such discussions. The decision will be in favor of majority of the community.
Writes at Dev Letters

Clipjump Clipboard Manager : More Scripts (updated 2019)

Image
User avatar
Avi
Posts: 193
Joined: 30 Sep 2013, 09:51
Facebook: avi.aryan.ap
Google: +AviAryan
GitHub: aviaryan
Location: India
Contact:

Re: AutoHotkey style guide

17 Feb 2016, 13:29

tidbit wrote:tutorial section 8.4 covers Indentation basics:
https://autohotkey.com/docs/Tutorial.htm#s84

1.2 covers my recommendation for hotkeys (not remaps) to newbies. multi-line, not single line. to try and prevent some common confusion:
https://autohotkey.com/docs/Tutorial.htm#s12

Also, I much prefer camelCase (lowerUpperUpper) over ProperCase. and hate things_with_underscores
I like the idea about using multi-line hotkeys. It helps keep things much logical.
I also like camelCase but only for variable and function names. For Class names and Commands, I like using ProperCase.
Writes at Dev Letters

Clipjump Clipboard Manager : More Scripts (updated 2019)

Image
User avatar
tidbit
Posts: 1126
Joined: 29 Sep 2013, 17:15
Location: USA

Re: AutoHotkey style guide

17 Feb 2016, 13:46

here's a summary of my preferences:
- camelCase (which means lowercase single words, like: if, else loop)
- { and } on their own lines, no OTB.
- if and friends don't use {}'s when only 1 action is needed
- if something is split among lines, align new lines
- tab indent the beginning of a line, spaces to align after that to align
- indent labels/hotkeys content
- no preference over labels or functions. they both have their uses
- always specify paths, don't rely on workingdir (use %a_scriptdir%\path\file.jpg)
- case for variables isn't the most important, but try and stay the same
- when helping someone, se weird/fun variable names, they often get confused and think stuff like "toggle" is an official AHK command
- comments are a lovely thing. People need to comment more. Comment as you go
- don't put spaces before after (), =, :=, etc (though, always a space before ( in if's and stuff)
- ALWAYS use ()'s with if's and friends.
- comma after a command is optional, but prefered
- force an expression in command parameters even if not needed. Better than guessing
- group related code chunks, (3 var definitions? 1 line after another. then a newline)
- labels and friends are separated by 2 blank lines, unless they "fall through" or are a bunch of 1-liners


example (notice the mix of tabs and spaces, it still looks nice):

Code: Select all

awesomeLabel:
	; no idea what to put in here.
	; lets just use some comments and talk to ourself.
	
	; filenames
	loop, %A_ScriptDir%\images\*.*
	{
		toolTip, %A_LoopFileName%
		sleep, 300
	}
return


label:
	; group similar actions
	pancake:=4
	deer:=2
	oatmeal:=strLen(subStr("12345687", 2))

	; not an assignment or whatever, so add a blank line.
	if (pancake=4 && deer=2)
		msgBox, % pancake "*" deer " = " pancake*deer ; math!
	else
	{
		msgBox, pancake = %pancake% ; no math!
		shortFunc("text", var, var, var)	
		
		; aligning
		; not every parameter needs its own line. such as if they are related and short
		; like x and y on one line, w and h and the next.
		; if you want to separate...
		shortFunc("text", var
                        , var+var
                        , var "str" var var "str")
		someLongerFunc("string string text" oatmeal, something
                      , x, y ; don't add an uncomfortable amount of spaces.
                      , w, h
                      , x2, y2
                      , w2, h2)
	}
return
rawr. fear me.
*poke*
Is it December 21, 2012 yet?
guest3456
Posts: 2528
Joined: 09 Oct 2013, 10:31

Re: AutoHotkey style guide

17 Feb 2016, 17:51

Avi wrote:
guest3456 wrote: i think you're confused
"style guides" are written by individual organizations to be used for anyone who contributes to their codebase. you just randomly happened to pick one from AirBnB. now if you wanted to submit a pull request to that repo, they would expect you to follow their styling guide.
i'm sure you can find 100s of different style guides for javascript.
The aim here is to make a style guide that majority of the community would find useful, that most of the community agrees in. I am well aware that creating a full-proof, universal style-convention isn't possible; there will always be rules people won't like agreeing to, and they are free to skip them.
guest3456 wrote:tabs instead of spaces? please.

A GitHub issue ( https://github.com/ahkscript/Ahk-Style-Guide/issues ) can be created for such discussions. The decision will be in favor of majority of the community.
you must have missed this part of my post. let me quote it for you:
guest3456 wrote: i appreciate the effort you're putting in, but like most of the repositories under the 'ahkscript' account, this doesn't belong as part of the org. i thought there was enough people clamoring in the past to remove all of those ridiculous repositories from the main org account and force the maintainers to stick them in this personal accounts. i guess it never happened

this should be your personal repo and your personal style guide, which can then possibly be linked from the awesome-ahk list, along with other style guides.

style guides are a personal preference thing, and you will never get agreement from the community, which is even another reason why this should be a personal repository rather than an organizational one


in case you don't understand, you will never get something 'most of the community agrees' with.

there is no official 'javascript community style guide'.
there is no official 'ruby community style guide'.
there is no official 'c++ community style guide'.
there is only an official python style guide because the syntax REQUIRES indentation for blocks instead of using braces

thats because style is personal. you're not the first person to try to attempt this, and you won't be the last. debates on this have spanned decades. tidbit's suggestions contradict yours. and i disagree with half of his. who cares?

there are however individual project style guides. which is where your style guide belongs. on your personal repo. if you get a decent amount of support, then it could be linked from the awesome-ahk list, as "Avi's AHK style guide".

User avatar
Avi
Posts: 193
Joined: 30 Sep 2013, 09:51
Facebook: avi.aryan.ap
Google: +AviAryan
GitHub: aviaryan
Location: India
Contact:

Re: AutoHotkey style guide

18 Feb 2016, 00:26

@tidbit Thanks for your input. I have added some things from your list and will surely add more.
guest3456 wrote: in case you don't understand, you will never get something 'most of the community agrees' with.

there is no official 'javascript community style guide'.
there is no official 'ruby community style guide'.
there is no official 'c++ community style guide'.
there is only an official python style guide because the syntax REQUIRES indentation for blocks instead of using braces

thats because style is personal. you're not the first person to try to attempt this, and you won't be the last. debates on this have spanned decades. tidbit's suggestions contradict yours. and i disagree with half of his. who cares?

there are however individual project style guides. which is where your style guide belongs. on your personal repo. if you get a decent amount of support, then it could be linked from the awesome-ahk list, as "Avi's AHK style guide".
I guess you're right. Coding Style is a broad term. As much as I will like to have a consistent coding style in Ahk (like Go and Python), I don't think it's possible and probably too much to ask for.
I renamed the repo to Ahk-Best-Practices , the gist now is
README.md wrote:Good practices in AutoHotkey coding that will help avoid bugs and make your code more readable.
I think this suites better. I have also removed some guidelines that look personal (like TAB indentation). What do you think ?
Writes at Dev Letters

Clipjump Clipboard Manager : More Scripts (updated 2019)

Image
guest3456
Posts: 2528
Joined: 09 Oct 2013, 10:31

Re: AutoHotkey style guide

18 Feb 2016, 01:09

i think "best practices" is a better name, but once you start including coding style stuff then again it will just end up being personal preference.

"best practices" that i would agree with are:

- must use indentation
- prefer := for expression based assignment (v2 will require this anyway)
- prefer to use if (xxx) for expression based if (v2 will require this anyway)
- your comment suggestions
- your hotkey suggestion to use 'return'

and i'd probably disagree with the rest. but i mean my opinion doesn't mean much

User avatar
jNizM
Posts: 2414
Joined: 30 Sep 2013, 01:33
GitHub: jNizM
Contact:

Re: AutoHotkey style guide

18 Feb 2016, 02:13

You should use your "best practice syntax" everywhere, not just in the right section:

Indentation
- A space before and after the "Expression Operators"
- The Command MsgBox with the right upper letters

But everyone has his own best practice. My would look like this:

Code: Select all

if (car = "old")
{
    MsgBox % "the car is really old"
    if (wheels = "flat")
    {
        MsgBox % "this car is not safe to drive."
        return
    }
    else
    {
        MsgBox % "Be careful! This old car will be dangerous to drive."
    }
}
else
{
    MsgBox % "My, what a shiny new vehicle you have there."
}
- if / else / return ==> small
- MsgBox and other Commands with the correct upper & lower letter like in the Docs
- use % and "" for strings to see them faster (different syntax color as strings with "")
- use 1 Tab = 4 Spaces
Image
[AHK] 1.1.30.01 x64 Unicode | [WIN] 10 Pro (Version 1803) x64 | [GitHub] Profile
Donations are appreciated if I could help you
User avatar
Avi
Posts: 193
Joined: 30 Sep 2013, 09:51
Facebook: avi.aryan.ap
Google: +AviAryan
GitHub: aviaryan
Location: India
Contact:

Re: AutoHotkey style guide

20 Feb 2016, 00:26

guest3456 wrote:i think "best practices" is a better name, but once you start including coding style stuff then again it will just end up being personal preference.
I agree. I will try not to add any stuff when there is not enough reasoning supporting that it is a "good practice" .
jNizM wrote:You should use your "best practice syntax" everywhere, not just in the right section:

Indentation
- A space before and after the "Expression Operators"
- The Command MsgBox with the right upper letters

But everyone has his own best practice. My would look like this:

Code: Select all

if (car = "old")
{
    MsgBox % "the car is really old"
    if (wheels = "flat")
    {
        MsgBox % "this car is not safe to drive."
        return
    }
    else
    {
        MsgBox % "Be careful! This old car will be dangerous to drive."
    }
}
else
{
    MsgBox % "My, what a shiny new vehicle you have there."
}
- if / else / return ==> small
- MsgBox and other Commands with the correct upper & lower letter like in the Docs
- use % and "" for strings to see them faster (different syntax color as strings with "")
- use 1 Tab = 4 Spaces
Image
Thanks. I will change all code to best practice later. I will also provide reasoning for all the points included as the best practices.

PS - Transferred the repo to my personal account for now. I will put it back when the project is suitable as the community guideline.
Writes at Dev Letters

Clipjump Clipboard Manager : More Scripts (updated 2019)

Image

Return to “Offtopic”

Who is online

Users browsing this forum: dmatch and 6 guests