v2 docs contribution questions

Discuss the future of the AutoHotkey language
SirRFI
Posts: 404
Joined: 25 Nov 2015, 16:52

v2 docs contribution questions

28 May 2018, 17:13

I am considering contributing v2 docs for a longer while, starting with renewed or additional code examples and small fixes. Actually I already have few things in mind.

However, before making up mind / doing anything, I'd like to know if:
• new examples are welcomed
• there are some guidelines to follow, such as starting if with upper-case, indentation style and so on
• is there anything else I should know



For code style, I use following:
• Naming: variable_name, methodAndFunctionName, ClassName
• Spaces: always after code-flow elements (if (something), while (something) etc.), none for calls (click(x,y), asd := new Banana())
• Parenthesis: yes
• Identation style: Allman's, alternatively { is in same line, after a space.

Code: Select all

Class A
{
	static arr := [ ; wish I could put [ in new line without Join - this probably makes the second IF style more consistent
		"a",
		"b",
		"c"
	]
	
	doSomething()
	{
		if (this)
		{
			; ...
		}
		else if (that)
		{
			; ...
		}
		
		; or
		if (this) {
			; ...
		}
		else if (that) {
			; ...
		}
	}
}
Use

Code: Select all

[/c] forum tag to share your code.
Click on [b]✔[/b] ([b][i]Accept this answer[/i][/b]) on top-right part of the post if it has answered your question / solved your problem.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: v2 docs contribution questions

28 May 2018, 23:38

I personally think that coding Style doesn't matter that much after all. And I think that new examples are always welcome.
Recommends AHK Studio
SirRFI
Posts: 404
Joined: 25 Nov 2015, 16:52

Re: v2 docs contribution questions

29 May 2018, 14:11

Coding style is of course personal preference, unless there's a rule / convention in a team. Given this, I believe there's some sense of consistency for the docs.
Use

Code: Select all

[/c] forum tag to share your code.
Click on [b]✔[/b] ([b][i]Accept this answer[/i][/b]) on top-right part of the post if it has answered your question / solved your problem.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: v2 docs contribution questions

29 May 2018, 14:38

Well I guess lexikos is the only one who can answer that.
Recommends AHK Studio
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: v2 docs contribution questions

29 May 2018, 14:39

- We could ask Ragnar to come up with an AHK documentation style guide, e.g. that states the preferences for the issues listed here:
your personal AutoHotkey style guide - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 17&t=47140
- You could ask Ragnar for any pages that need more examples, or you could collect a personal list of examples in a separate thread (that you think the documentation would benefit from), or you could write a complete/incomplete beginner tutorial.
- I've collected some examples here:
jeeswg's documentation extension tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=33596
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: v2 docs contribution questions

29 May 2018, 16:27

on a side note, why the use of & ?? the only reason i can come up with is for consistency's sake, but then again, why was this done in the first place?
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: v2 docs contribution questions

29 May 2018, 16:38

@swagfag: Do you mean & with NumGet/NumPut?
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: v2 docs contribution questions

29 May 2018, 16:46

no, i forgot to quote sirrfi:
Coding style is of course personal preference, unless there's a rule / convention in a team. Given this, I believe there's some sense of consistency for the docs.
specifically, the html encodings
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: v2 docs contribution questions

30 May 2018, 02:34

Referring to the already existing code examples in the documentation, the following coding style dominates (and most of them was preferred by Chris who invented AHK and originally wrote this documentation):
  • Control flow statements such as "if" are lower case, except Loop, Gosub, Goto and Until, and are followed by 1 space
  • Declaration keywords such as "static" are lower case, except ByRef
  • Directives, variables, functions, methods and properties are upper camel case, for example: #NoTrayIcon, A_TitleMatchMode, IsDone, Click(), MsgBox, MyObject.Method(), MyObject.Property (in case of doubt always use the case as defined on the corresponding page)
  • Omit parentheses where possible. For example: if IsDone, MsgBox "This is a string."
  • Indentation size is 4 spaces
  • Indentation style is Allman
  • The comment symbol is followed by 1 space
  • On the right side of a statement, the comment symbol is preceded by minimum 2 spaces
  • If a comment describes the following line(s), it usually ends with a colon
  • If a comment describes the statement on the left side, it usually ends with a period
  • Comments are enclosed in the EM tags (to colorize them), for example: <em>; Comment.</em>
In addition, you should pay attention to the following:
  • For readability, the lines should not be too long, especially for mobile device users (max 80 chars?)
  • Check spelling and grammar
  • New examples should fit to the current page and should not consist of an excessive number of lines.
Let me know if I forget something.
swagfag wrote:on a side note, why the use of & ?? the only reason i can come up with is for consistency's sake, but then again, why was this done in the first place?
&, < and > belong to HTML. Changing them to &, < and > is a preventive measure to prevent them from being accidentally recognized as HTML.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: v2 docs contribution questions

30 May 2018, 05:29

@Ragnar: Fantastic, thanks so much for this.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: v2 docs contribution questions

30 May 2018, 07:11

jeeswg wrote:- We could ask Ragnar to come up with an AHK documentation style guide, e.g. that states the preferences for the issues listed here
i second this, but make it a readme.md in the repo or something
SirRFI
Posts: 404
Joined: 25 Nov 2015, 16:52

Re: v2 docs contribution questions

30 May 2018, 11:58

Sounds fine to me, except for following:
Ragnar wrote:[*]Omit parentheses where possible. For example: if IsDone, MsgBox "This is a string."
Since the "commands" are now functions, it would be better to use ()'s for consistency and similarity with other languages. Consider someone falls onto one of following ideas, judging by the examples of inbuilt functions:

Code: Select all

MsgBox myFunc "SPARTA"
myFunc(a)
{
	return "This is " a "!"
}

ToolTip otherFunc
otherFunc()
{
	return "Puff"
}

if thirdFunc
	MsgBox("So, this is true.")
thirdFunc()
{
	return true
}

In addition, I think this reduces readability and reliability as soon things get little more complex.
Wouldn't it be better to use parenthesis and teach people ahead of time?
Use

Code: Select all

[/c] forum tag to share your code.
Click on [b]✔[/b] ([b][i]Accept this answer[/i][/b]) on top-right part of the post if it has answered your question / solved your problem.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: v2 docs contribution questions

30 May 2018, 12:18

You're using lower camelCase. I think starting since AHK v1.1 it would be nice to differ between Classes and variables by using upper for classes and lower for variables/functions.
But thats just my personaly taste I guess.
Recommends AHK Studio
SirRFI
Posts: 404
Joined: 25 Nov 2015, 16:52

Re: v2 docs contribution questions

30 May 2018, 12:59

nnnik wrote:You're using lower camelCase. I think starting since AHK v1.1 it would be nice to differ between Classes and variables by using upper for classes and lower for variables/functions.
But thats just my personaly taste I guess.
Such change would require to change all occurances for each variable / function / etc. in all docs. Shouldn't be much of an issue, but still.
Use

Code: Select all

[/c] forum tag to share your code.
Click on [b]✔[/b] ([b][i]Accept this answer[/i][/b]) on top-right part of the post if it has answered your question / solved your problem.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: v2 docs contribution questions

30 May 2018, 14:08

No we can keep both standards for now and do a slow transition.
Just add new stuff to the docs using lower camelCase and when working on old examples you might also change them.
Recommends AHK Studio
User avatar
kczx3
Posts: 1640
Joined: 06 Oct 2015, 21:39

Re: v2 docs contribution questions

30 May 2018, 14:48

nnnik wrote:You're using lower camelCase. I think starting since AHK v1.1 it would be nice to differ between Classes and variables by using upper for classes and lower for variables/functions.
But thats just my personaly taste I guess.
I would agree with this. It is very similar to how components are defined in ReactJS. Components are CamelCase whereas variables, functions, methods, etc are normal camelCase.
SirRFI
Posts: 404
Joined: 25 Nov 2015, 16:52

Re: v2 docs contribution questions

30 May 2018, 14:59

Decent editor can find all occurrences in file tree, it's just that you need full list of things to change.
Use

Code: Select all

[/c] forum tag to share your code.
Click on [b]✔[/b] ([b][i]Accept this answer[/i][/b]) on top-right part of the post if it has answered your question / solved your problem.
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: v2 docs contribution questions

01 Jun 2018, 21:17

SirRFI wrote:Since the "commands" are now functions, it would be better to use ()'s for consistency and similarity with other languages.
That is subjective, and perhaps a matter of language design rather than documentation style. It seems this topic isn't about the former, but the latter. The language currently allows parentheses to be omitted, so the documentation should reflect that, and should demonstrate where that can be used to best effect. I generally omit parentheses where I feel it improves readability, but that's not in every case (like "when things get more complex"). Since readability is subjective, I would simply suggest that you try to be consistent with the examples already present in the documentation.
nnnik wrote:I think starting since AHK v1.1 it would be nice to differ between Classes and variables by using upper for classes and lower for variables/functions.
Be careful about adopting conventions or habits from case-sensitive languages. If a users learns by example that MyFoo is a class and myFoo is an instance or some other variable, they may forget that variable names are not case-sensitive.

I sometimes prefer to use lower for local variables and upper for functions and global variables. That might come out looking very similar (since most classes are global variables), but I think the distinction of scope is more relevant to AutoHotkey than whether the variable was created by a class definition or not. I suppose it could have the same issue, but it doesn't seem as likely.

Return to “AutoHotkey Development”

Who is online

Users browsing this forum: No registered users and 34 guests