GMLscripts.com

xot

Administrator

Registered: 2007-08-18

Posts: 1,240

GameMaker Studio 2 style guide discussion

The scripts on the site are painfully out-of-date with regard GameMaker Studio 2. Most of them work fine, a few have compatibility problems or could take advantage of new features, but all of them need some love.

Personally, I'm pretty happy with the established style guide. Sometimes I'm not great at enforcing it completely but most things conform closely to it. I'm very happy to hear thoughts and suggestions about refining or altering the general code style used here.

However, one area that I think needs immediate attention is the comment header. GameMaker Studio 2 supports JSDoc comments. Vitally, this is the new (and only) way to support syntax hints. The GameMaker Studio 2 way to do things resembles this:

Expand/// @function is_same_object(id, object)
/// @description Compare an instance object index with that of another.
/// @param {real} instance_id The unique instance ID value of the instance to check.
/// @param {real} object_index The object index to be checked against.

I'm looking for suggestions for a new header style. It needs to be functional, easy to read, and aesthetic. If possible, I'd like to see some continuity with the current style. Also, script description blocks need to be easily and reliably identifiable by the code running the site. Right now I use regular expressions to extract the first sentence of the description to form the script summaries. JSDoc @description tags would probably fill that role. A more detailed description could appear elsewhere in the comment header block. The important thing is that the script is initially described as completely as will fit in a single brief sentence (and thanks to JSDoc, a single line).

Below is my best attempt at satisfying the above, a hybrid style that is clearly tacked onto the existing style.

Expand/// @func   string_left(str,num)
///
/// @desc   Returns a number of characters from the start of a string.
///         If the number of characters given is negative, the string 
///         will be shortened by that amount.
///
/// @arg    {string}    str         string
/// @arg    {real}      num         number of characters to return
///
/// @return {string}    a number of characters from start of string
///
/// GMLscripts.com/license

The idea with this hybrid was to make scripts equally at home in GMS2 and GMS1.4, as well as try to make the best of a new documentation system I find hideous looking. Blocks are consistently indented for readability and aesthetic reasons. I was surprised to learn today that GMS1.4 will ignore @func and correctly interpret the syntax definition. It is slightly vexing that @return is the shortest JSDoc synonym for @returns. I prefer the short tags to economize horizontal space. It's sometimes difficult to fit a good description into 80 columns and JSDoc tags make it so much harder. I'm willing to flex a little on line lengths but it can prove to be an issue when printing scripts. I have omitted an explicit @license tag purely for aesthetic reasons but maybe it should be used.

My feelings on hybridization are mixed. I'm leaning towards making a clean break from GMS1.4 which is at end-of-life. A tiny survey suggests most people have moved onto GMS2. Regardless, scripts that can support both engines are not always possible, so there is going to have to be some segregation. How to manage this is an important decision yet to made for the Git repo.

Please share any thoughts or concerns below. Thanks.

---

Abusing forum power since 1986.

Thijsmie

Member

Registered: 2018-11-02

Posts: 1

Re: GameMaker Studio 2 style guide discussion

Nice! What about combining it with argument lists though? I am not a fan of the:

Expandvar x,y;
x = argument0;
y = argument1;

I personally use:

Expandvar
x = argument0, /// @param int x
y = argument1; /// @param int y

Last edited by Thijsmie (2018-11-02 17:16:13)

xot

Administrator

Registered: 2007-08-18

Posts: 1,240

Re: GameMaker Studio 2 style guide discussion

I can see the appeal of this but having the parameter/argument information outside of the header is not something I'm comfortable with. Things get a little more messy with optional arguments making it harder for find documentation. That information can be included in the header as well but then the parameter duplication seems a little clunky. Admittedly, these are just my gut reactions. I'm happy to hear more discussion about it.

It does bring to mind a change I'm considering for the style guide. I've become fond of this structure to initialize argument variables at the top of a script.

Expandvar a = argument0,
    b = argument1,
    c = argument2;

---

Abusing forum power since 1986.

Juju

Member

Registered: 2015-10-01

Posts: 45

Re: GameMaker Studio 2 style guide discussion

I say move entirely to GMS2. It'd be great if it was possible to have a legacy GMS1 version of the site to cover users still on that version, but you've gotta make a clean break at some point.