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: 2825
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

The eScript style guide.

Post by Yukiko »

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.
Nando
POL Developer
Posts: 282
Joined: Wed Sep 17, 2008 6:53 pm
Contact:

Re: The eScript style guide.

Post by Nando »

The page was set to private, I've changed it to public now. :)
DevGIB
Grandmaster Poster
Posts: 248
Joined: Mon Feb 06, 2006 6:12 am

Re: The eScript style guide.

Post by DevGIB »

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: 2825
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko »

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.
RusseL
Forum Regular
Posts: 375
Joined: Fri Feb 20, 2009 8:30 pm

Re: The eScript style guide.

Post by RusseL »

Agree with spaces instead of tabs:)
Spaces are everywhere spaces, and tabs can differ.
Yukiko
Distro Developer
Posts: 2825
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko »

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.
Yukiko
Distro Developer
Posts: 2825
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko »

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.
Yukiko
Distro Developer
Posts: 2825
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko »

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.
Yukiko
Distro Developer
Posts: 2825
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko »

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.
ThisIsMe
Distro Developer
Posts: 101
Joined: Sun Jul 17, 2016 1:29 am
Contact:

Re: The eScript style guide.

Post by ThisIsMe »

A bit late but it looks good.
Yukiko
Distro Developer
Posts: 2825
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko »

Thanks ThisIsMe. I'll fix the spelling errors you mentioned.
User avatar
andenixa
Grandmaster Poster
Posts: 105
Joined: Tue Nov 09, 2010 1:33 am

Re: The eScript style guide.

Post by andenixa »

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: 2825
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko »

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.
User avatar
andenixa
Grandmaster Poster
Posts: 105
Joined: Tue Nov 09, 2010 1:33 am

Re: The eScript style guide.

Post by andenixa »

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: 2825
Joined: Thu Feb 02, 2006 1:41 pm
Location: San Antonio, Texas
Contact:

Re: The eScript style guide.

Post by Yukiko »

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. :)
xeon
Forum Regular
Posts: 338
Joined: Fri Oct 31, 2008 3:18 am
Location: Italy

Re: The eScript style guide.

Post by xeon »

I've to read it sometime :cheesy:
Post Reply