HISE Script Coding Standards

[d.healey]

I'm currently working on a project with other developers and we thought it would be a good idea if we had some kind of coding standard or style guide. The ultimate goal is to allow multiple people to work on a script and have it look as though it was written by a single hand. It doesn't quite work like that in practice but it gets us some of the way there and it makes it much easier to understand each other's code.

I've added the document to my fork of the HISE documentation repository, I'd like to get your feedback and ideas on it, and would love @Christoph-Hart's input especially. And please let me know if you spot any typos (I'm sure there are still lots).
https://github.com/davidhealey/hise_documentation/blob/master/scripting/scripting-in-hise/hise-script-coding-standards.md

[andioak]

@d-healey Very nice page, will check it out in detail. But this is new to me:

const var foo = a || b;
const var bar = !c;

Very efficient.

[d.healey]

@andioak It seems const var foo = a || b; doesn't work as I expected in HISE Script (works in regular JS though), I'll remove it from the doc.

[andioak]

@d-healey aaaaaash, looked so neat. :)

[ulrik]

@d-healey This is a great initiative!
I will read this and learn a lot, for instance, declare iterator with local, nice reading!
Just after the “local i “ I found you write an inline function like this:

inline function initPageButtons()
{
    local p = [];
    for(i = 0; i < 16; i++)
    {
        p.push(Content.getComponent("PageButton" + i));
    }

    return p;
};

[d.healey]

@ulrik said in HISE Script Coding Standards:

@d-healey This is a great initiative!
I will read this and learn a lot, for instance, declare iterator with local, nice reading!
Just after the “local i “ I found you write an inline function like this:

inline function initPageButtons()
{
    local p = [];
    for(i = 0; i < 16; i++)
    {
        p.push(Content.getComponent("PageButton" + i));
    }

    return p;
};

That example is pure Christoph.

[ulrik]

@d-healey

[d.healey]

What's everyone's opinion on writing fixed constants at the top of your scripts/namespaces like this:

const var NUM_SAMPLERS = 6;

Instead of this
const var numSamplers = 6;

I like the idea that whenever you see something in all caps you'll know exactly what kind of variable it is and where to look for its declaration.

[ustk]

@d-healey This is what I tend to do, well, when I don't forget at least...

[andioak]

@d-healey It defines certain stuff better and looks nice and distinct. Crossing languages often tends to make me a bit confused and cautious, since some (KSP for ex.) languages reserve upper case vars. Not sure about normal JS though. Does hise interpreter/C++ side use this that could cause conflicts? Anyway, could get over the cautiousness for that distinct look. It definitely pops out at you in a dense script.

[Lindon]

@d-healey its what I do too...

[Christoph Hart]

Good idea and yes, definitely go for the ALL_CAPS constants.

I'll go through it and do a pull request for the stuff I find, but it's mostly spot on.

I would also recommend that for performance-related coding tips, you include a benchmark of the good and bad result so that people can directly see the benefit. Here's for example a minor tip to call reserve() before pushing large amounts of data:

const var NUM_ELEMENTS = 100000;
const var badList = [];
const var goodList = [];

Console.start();

for(i = 0; i < NUM_ELEMENTS; i++)
    badList.push(i);
 
Console.stop(); // ~41ms

Console.start();

goodList.reserve(NUM_ELEMENTS);
for(i = 0; i < NUM_ELEMENTS; i++)
    goodList.push(i);

Console.stop(); // ~39ms

The 5% perfomance benefit of this tip may not be enough to be taken into a "official" coding style doc though :)

[d.healey]

@Christoph-Hart I've added the note about the reserve() keyword, I think it's good to have it there as a reminder (I always forget about it!). I also added the rule for all caps constants and tweaked a few other bits. Adding benchmarks is a good idea, I'll go through the examples and add this when I have a bit of spare time.

[ulrik]

@d-healey Now I've read the scripting standards at least 4 times, and for me it's really good to have this document, I learn a lot and understand more and more of the complexity in scripting, and also why the standards makes it so easier to understand the code.
Thank you once again for making this document!

[ulrik]

@d-healey Oh I forgot to ask, in the doc you say:
"Prefer MIDI Lists over arrays when possible, especially for storing polyphonic data."

How do a MIDI List work, is it an array with all the array functions?

[d.healey]

@ulrik I think Christoph explained it well here - https://docs.hise.audio/scripting/scripting-api/midilist/index.html

[ulrik]

@d-healey Thank you!

[andioak]

@d-healey said in HISE Script Coding Standards:

@ulrik I think Christoph explained it well here - https://docs.hise.audio/scripting/scripting-api/midilist/index.html

Question for @d-healey and @Christoph-Hart : Can a MidiList array store multiple dimensions of data? Like a multi-dimensional array?

I ask cause an important KSP script I am trying to recreate use a polyphony script containing 128x4 values that look for amounts of current equal note hits. Would I be able to nest midi-lists in a normal array? Or do they come with multi-depth features?

Additional question. Is there a performance overhead using MidiLists over a normal array/nested arrays when accessing specific / one-time data, not looped, but like this: var get_my_value = my_array[0][3] ? Or is the performance in the iteration?

[d.healey]

@andioak A MIDI List is a single dimension array with 128 elements that can store numbers. Yes you can store MIDI Lists in an array.

[andioak]

@d-healey Okay, thanks. Will probably be using lots of those then. :)