The eScript style guide.

Discussion about the development of POL's official distribution scripts.

Moderators: POL Developer, Distro Developer

Post Reply
Yukiko
Distro Developer
Posts: 2505
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

The eScript style guide.

Post by Yukiko » Sat Jul 29, 2017 7:21 pm

I've created a page with the eScript style guide. I think this was originally written by Austin. I made a couple modifications but nothing major. This guide is a "general" coding guide. I think there should be a section added at the end for submissions to the Distro, "Distro submission guidelines" or something along those lines. So take a look. Critique it and post any thoughts here.
Sincerely,
Yukiko

I would tell you a UDP joke but you might not get it.

Titus 2:13

Nando
POL Developer
Posts: 260
Joined: Wed Sep 17, 2008 6:53 pm
Contact:

Re: The eScript style guide.

Post by Nando » Sun Jul 30, 2017 7:39 am

The page was set to private, I've changed it to public now. :)

DevGIB
Grandmaster Poster
Posts: 204
Joined: Mon Feb 06, 2006 6:12 am

Re: The eScript style guide.

Post by DevGIB » Sun Jul 30, 2017 6:36 pm

Only other things which i didn't notice in the guide.
  • Spacing
  • Indentation
Preference on spacing:
if( variable )
or
if(variable)

and indentation:
using spaces or tabs to indent functions, if statements, case statements etc.

Yukiko
Distro Developer
Posts: 2505
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko » Mon Jul 31, 2017 7:19 am

Nando wrote:
Sun Jul 30, 2017 7:39 am
The page was set to private, I've changed it to public now. :)
Hmm... I though I dotted all my Ts and crossed all my Eyes :)
I guess I need to recheck my check boxes.
DevGIB wrote:
Sun Jul 30, 2017 6:36 pm
Only other things which i didn't notice in the guide.
  • Spacing
  • Indentation
Preference on spacing:
if( variable )
or
if(variable)

and indentation:
using spaces or tabs to indent functions, if statements, case statements etc.
Hey! We agree on something. :)
As regards the leading and trailing spaces inside parenthesis, that was an oversight on my part. I intended to edit them out. I copy/pasted from Austin's (I think it was his work.) Style Guide. I think I posted that at the end of a long night/morning and was in a hurry to get it up for review. I'll revise it soon.

Indent, indent, INDENT! Very important.
I used to be a tabs only guy but after hearing a discussion on the Daily Tech News podcast about tabs vs. spaces I've mixed feelings. They mentioned that a majority of coders who were surveyed preferred spaces for indents because of the way editors handle, or mis-handle, tabs but I still lean strongly to the tabs side of the argument.
Sincerely,
Yukiko

I would tell you a UDP joke but you might not get it.

Titus 2:13

RusseL
Forum Regular
Posts: 349
Joined: Fri Feb 20, 2009 8:30 pm

Re: The eScript style guide.

Post by RusseL » Mon Jul 31, 2017 2:41 pm

Agree with spaces instead of tabs:)
Spaces are everywhere spaces, and tabs can differ.

Yukiko
Distro Developer
Posts: 2505
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko » Wed Aug 02, 2017 11:13 pm

Ok. I have posted what I hope to be the final revision of the eScript style guide.The only thing I did not add was the tutorial for submitting patches and submissions via GitHub. I don't think right now we need to worry about it but as things get busier and user base grows it will probably become necessary. So if one of the community would write that tutorial I would appreciate it. You should keep in mind that I want the target audience of the tutorial to focus on someone relatively new to GitHub if possible.
Sincerely,
Yukiko

I would tell you a UDP joke but you might not get it.

Titus 2:13

Yukiko
Distro Developer
Posts: 2505
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko » Wed Aug 02, 2017 11:21 pm

Well, I need to make one l;ast major edit. I see that the page addon for PHPBB doesn't handle tabs correctly. :P
Hence no indents.
Sincerely,
Yukiko

I would tell you a UDP joke but you might not get it.

Titus 2:13

Yukiko
Distro Developer
Posts: 2505
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko » Wed Aug 02, 2017 11:38 pm

It seems to strip leading white space from the document so even changing the tabs to spaces didn't work. I had to enclose the code examples in the BB Code code block.
Sincerely,
Yukiko

I would tell you a UDP joke but you might not get it.

Titus 2:13

Yukiko
Distro Developer
Posts: 2505
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko » Sat Aug 05, 2017 9:22 pm

I've edited the Style Guide and made a few changes. Take a look and let me know what you think. I can't think of anything else to add or that needs changed. So this should be the final version.
Sincerely,
Yukiko

I would tell you a UDP joke but you might not get it.

Titus 2:13

ThisIsMe
Distro Developer
Posts: 64
Joined: Sun Jul 17, 2016 1:29 am
Contact:

Re: The eScript style guide.

Post by ThisIsMe » Fri Aug 18, 2017 6:11 pm

A bit late but it looks good.

Yukiko
Distro Developer
Posts: 2505
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko » Fri Aug 18, 2017 9:32 pm

Thanks ThisIsMe. I'll fix the spelling errors you mentioned.
Sincerely,
Yukiko

I would tell you a UDP joke but you might not get it.

Titus 2:13

User avatar
andenixa
Grandmaster Poster
Posts: 105
Joined: Tue Nov 09, 2010 1:33 am

Re: The eScript style guide.

Post by andenixa » Sun Aug 27, 2017 4:06 am

I think its brilliant that you made this coding style. I would probably succumb to using one of the pre-existing code convention (something akin to PEP8), yet a fresh look yields nicer things!

Note: spells that are cast via conventional means (like a spellbook) would also have spellId argument passed to the program block, such that:

Code: Select all

program spell_GreatHeall(caster, spellid)
endprogram
Also you can do:

Code: Select all

var string := "Hello there {}. I am {} years old.".format("Stephen.", math);
Which is much less byte-code than string concatenation (which you can easily check via -l flag to ecompile).

A neat trick though (actually comes from Java) if you need to convert something to string is to do:

Code: Select all

var myMath := 21;
var myString := "" + myMath; // to convert it to String instead of calling CStr();
Which is slightly faster (probably because Value Stack isn't used).

As a side note I don't think empty return statement is bad:

Code: Select all

return;
It just returns an uninit object which is a singleton instead of doing extra SizeOf(BObject) malloc that is ~200bytes just to make BLong: 0 / 1 return values. Unless of course you need a definite return value.

I would also not encourage any kind of cameCasing in filenames.

The majority of newcomers run POL at Windows OS which is case insensitive and may mangle filename case (many text editors do) making a script base Linux incompatible. Because of that I suggest to keep all filenames strictly lowercase.


PS: For Pete's sake get rid of ':=' in favor of '=' .. or make the two to co-exist!

Yukiko
Distro Developer
Posts: 2505
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko » Sun Aug 27, 2017 7:43 pm

Now I remember you. I knew I recognized your name but I just couldn't remember. But when you mentioned the string format item it came back to me. That addition to the Core was submitted by you. Anyway, it's good to see you back here.

I have to say that I don't want to see := get replaced by =
Don't ask me for a logical reason because I haven't given the idea any thought. For now I'll just say I like :=
Well, now that I think about it I do have one good reason. If scripters thought that deprecating the 'global' and 'local' variable declarations and the single '=' equality check for the double equals '==' caused code to break just think of the difficulty of updating all your scripts from ':=' to '='.

As for Camel Case in filenames, it does make the "readability" better but I'm actually in favour of the first letter of every word being capitalized, ie. SpellStarter.src rather than spellStarter.src or spellstarter.src. In my opinion the first, or second, example is more "readable" than all lower case.

I see your point about empty returns and it's a good point. I wasn't aware of what actually happens behind the scenes when you have a return with a value attached. The reason I like a zero or a one after a return is again for readability. When I see a return 0 I immediately know it's a return from a failure or at least it most likely is. I know there are situations where you'd want to return 0 for other reasons.

And thanks for the tip with the following example:

Code: Select all

var myString := "" + myMath; // to convert it to String instead of calling CStr();
I didn't realise that would work.
Sincerely,
Yukiko

I would tell you a UDP joke but you might not get it.

Titus 2:13

User avatar
andenixa
Grandmaster Poster
Posts: 105
Joined: Tue Nov 09, 2010 1:33 am

Re: The eScript style guide.

Post by andenixa » Tue Aug 29, 2017 5:21 am

I agree that readability counts and you probably shouldn't confuse your readers with what I said.


As for assignment the need to push a combo of 3 keys to type := instead of 1 key for =
is annoying. My guess is that Eric Swanson was fond of Pascal syntax much thus the syntax. Its has some history to it which is of little relevance to newcomers and only creates extra clutter.
I made the two operators to have the same functionality the first thing when the Team had released POL source core. I didn't submit the patch as Austin weren't very sure if he wants it in the official core.

The stuff mentioned about memory allocation is of little concern unless you have a really huge code base and a lot of clients, I am talking thousands here.
I return 0/1 as well for functions and scripts which output actually matters (though I prefer error{errortext="<describe what happened here>"} on failures). There is a little trick to make it look slightly more clear:

Code: Select all

enum true_false
    false,
    true
endenum
Then just return false on failure and true on success.

Note that while eScript is case-insensitive constants and enums are. Hence returning False, FALSE, and fAlSe won't compile in a script that uses these constants. You probably already knew it yet still might be worthwhile to put this to your guide. Its not very obvious feature of eScript for beginners (and everyone else;)).

Yukiko
Distro Developer
Posts: 2505
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko » Tue Aug 29, 2017 10:31 am

I was aware of the constant case sensitivity but not the enum. I guess I never encountered it because I usually maintain case when entering variablesetc.

Your tips are very useful. I would invite you to write a tips and techniques guide. I would love to add it to our pages. :)
Sincerely,
Yukiko

I would tell you a UDP joke but you might not get it.

Titus 2:13

xeon
Forum Regular
Posts: 333
Joined: Fri Oct 31, 2008 3:18 am
Location: Italy
Contact:

Re: The eScript style guide.

Post by xeon » Mon Sep 18, 2017 1:52 pm

I've to read it sometime :cheesy:
Scripter Xeon | Zulu Hotel Italia 7th Age | www.zhi.it
Image

Post Reply