Posting code on the Programming Forum: Do's and Dont's

FrostyCat

Redemption Seeker
Posting code on the Programming Forum:
Do's and Dont's

GM Version: ALL
Target Platform: ALL
Download: N/A
Links: N/A

It has come to my attention that many novices are inconveniencing themselves by posting code questions in poor form. Here are some guidelines for doing it right and giving responders a good first impression.

Summary
Do:
  • Post code using code tags (i.e. between [code] and [/code])
  • Comment adequately, but not excessively
  • Cite where the code comes from and your exact GM version
  • Indent your code
  • Write with your best grammar and style
Don't:
  • Post screenshots or videos of code
  • Post code in plain text
  • Paraphrase code without citing the original
  • Ignore the Manual's instructions (AKA "throwing TLDR cards at the Manual")

Do: Post code using code tags

This is important for two reasons. First, it stops the forum's BBCode and emoji parser from clobbering your code. Second, it typesets the code in monospace and preserves all spacing, which makes it easier for developers to check for things like indents and exact character correspondances.

Do: Comment adequately, but not excessively


Adding comments helps improve the readability of your code and gives responders an insight into your assumptions. But don't do it to the point that actual lines of code become isolated from each other. Generally, your comments should look like a rough paraphrase alongside your active code.

Do: Cite where the code comes from

Context matters when it comes to coding. Whenever you post a code fragment, explicitly indicate the script/room/object+event combination where it comes from, in case that's where your mistake is. Remember: Good code in a bad spot is bad code.

Do: Cite your exact GM version

GM is a living piece of software, and that means code and setups can be correct in one version but not in another. To avoid confusion later, cite the full version number (e.g. 1.4.1763) somewhere in your response. This also allows responders to give you appropriate recommendations if your GM version is a potential problem.

Do: Indent your code

Code indentation documents the nesting form of your control structures, and are instrumental in helping you and responders spot problems in your code. Standard styles commonly used in GML include Allman, K&R and Whitesmith. It's OK to have a different indentation style from your responders, but it's not OK to not have one at all or adopt one that isn't well-documented just to be unique.

Allman:
Code:
if (foo)
{
    bar();
    while (baz(a, b, c))
    {
        qux();
    }
}
K&R:
Code:
if (foo) {
    bar();
    while (baz(a, b, c)) {
        qux();
    }
}
Whitesmith:
Code:
if (foo)
    {
    bar();
    while (baz(a, b, c))
        {
        qux();
        }
    }
Do: Write with your best grammar and style.

There's no need for formal style here, but that doesn't mean writing like a cretin won't get in your way. Punctuate sensibly, be direct and spell to the best of your ability. If you want responders to care, don't give the impression that you don't.

Don't: Post screenshots of code


Code in screenshots can't be copy-and-pasted, can be obscured by scroll bars if long enough, and can suffer from link rot if externally linked. Save responders and future users the hassle and post code as text in code tags whenever you can.

Exception: If you have tracked down the problem via the debugger, post a full screenshot of it with the applicable watch panes. Still, you should include the code displayed using code tags, especially if there is more hidden by scroll panes on the screenshot.

Don't: Post videos of code

This is even worse than posting screenshots of code. Lossy video compression and inadequate capture resolution can make "dotty" characters like semicolons and dots disappear into a blur. In addition, responders don't want or need to waste time seeking the right frame to find the code.

Exception: Do provide a link to a video if you got the code from one. Use a link with an embedded time parameter so that responders don't have to waste time finding the right frame.

Don't: Post code in plain text

If you aren't convinced why this is a bad idea, look at this example:

for (var i = 0; i < 6; i++;) {
array = i*2;
}


It looks like I'm incorrectly setting array over and over again, but in fact there is an array in there --- the [i] got escaped into BBcode. The indentation is also gone, and the ;) just before the starting brace turned into an emoticon. It's a total mess, and the same can happen to you if you give code tags the cold shoulder.

The equivalent in code tags, on the other hand, appears in verbatim:
Code:
for (var i = 0; i < 6; i++;) {
  array[i] = i*2;
}
Don't: Paraphrase code without citing the original

A lot can go wrong from intuition to keyboard, especially if you are a novice in GML. If you want to summarize your code, fine, but make sure the original code is available via a code tag or link so that your assumptions can be cross-checked. You aren't making it any easier by making responders guess at your code.

Don't: Throw TLDR cards at the Manual

If a function doesn't do what you expect it to do or if you don't know at all, read the Manual's description of it and check out the example at the bottom before posting. Not reading the Manual first doesn't mean you're new, it means you're negligent.
 
Last edited:
K

Kuro

Guest
Nice guide! I didn't realise there were names attached to the style conventions. While I've always been a sucker for Allman, I've also had an appreciation of the compactness of the K&R style, but never used it because I didn't like the brackets not being aligned to another bracket. Discovering that these conventions had names prompted me go look them up wherupon I discovered more standards. Some of which I had never noticed before. In particular one called Ratliff looks pretty neat because it has K&R style of the top bracket but also gives the bottom bracket something to be aligned to. I might start using it. Learn something new every day. Thanks :D

Update: So it turns out that using Ratliff style for a week did wean me off Allman, but had the unexpected side effect of making me prefer K&R. lol
 
Last edited by a moderator:

FrostyCat

Redemption Seeker
Nice guide! I didn't realise there were names attached to the style conventions. While I've always been a sucker for Allman, I've also had an appreciation of the compactness of the K&R style, but never used it because I didn't like the brackets not being aligned to another bracket. Discovering that these conventions had names prompted me go look them up wherupon I discovered more standards. Some of which I had never noticed before. In particular one called Ratliff looks pretty neat because it has K&R style of the top bracket but also gives the bottom bracket something to be aligned to. I might start using it. Learn something new every day. Thanks :D
Allman for me,

K&R just looks ugly as it can get, Its prob good if youre aiming to be fast
ALLMAN *clap,clap,clap*, ALLMAN *clap,clap,clap*, ALLMAN *clap,clap,clap*...
As primarily a K&R user, I get these "you don't see the start of the blocks", "you're just being cheap with lines" and "you're being heretical" comments a lot from Allman users. Perhaps I should present my side of the story.

Those of us on K&R don't live around lining up braces like Allman or Whitesmith. We live around starting and ending block statements, the opening brace is only for the compiler to read. We still see where control structures start and end, we just focus on different pairings.

Languages like Unix shell scripting and the alternative block syntax for PHP demonstrate the idea of how K&R coders think. These don't use braces to delineate control structures, but a corresponding keyword to end them. Here are some examples:
Code:
# Unix shell --- xyz and zyx
if [ -z $2 ]; then
  echo "No argument 2"
fi
Code:
<!-- Alternative PHP block syntax --- xyz and endxyz -->
<?php if ($_GET['q'] == "Hello World!"): ?>
  <p>Bonjour!</p>
<?php endif; ?>
K&R is the direct descendent of these forms of organization in curly-brace languages, where the ending keywords all map back to the closing brace.

Quite surprisingly we K&R users usually know why Allman and Whitesmith users think the way they do, but not vice versa. That can and should change.
 
Last edited:
K

Kenjiro

Guest
Code:
if foo=foobar then
    print "food"
end if
This is why I use one = instead of == in if statements.
This will bite you in the behind if you ever move on to other languages.

Do this in C/C++ and you'll be assigning the value of foobar to foo, giving you weird, hard to find bugs.

Of course, if you plan on staying with GML for the rest of your life and have no intentions of ever writing DLL's or Dynlib extensions for GM, then you won't have a problem.
 
K

Kenjiro

Guest
Not understanding why you'd go out of your way to change your coding style, in that case.
 

The-any-Key

Member
Not understanding why you'd go out of your way to change your coding style, in that case.
Like challenges.

My day goes like:
Coding PHP Double =
*alt+tab.
Coding GML single =

But it may be insanity.

Or maybe little of both :)

And it keeps things interesting :)
 
Last edited:

John Andrews

Living Enigma
Really good tips! I was thinking of doing a tutorial on platformers and now I'll take in count these useful advices! :)
 
This is a GREAT guide! I wish ALL the forums I visit had something like this to make it easier for everyone.

WAY too many times there's the posts "X doesn't work. HELP!!!" and thats the entire post. Adequate information around an issue is essential in getting resolution.

Not using code tags make it overly complicated, for all the reason you stated. Each site does strange things to code on their text parsers that just clean it up using a code tag; and the better part is the code tags are scrollable and keep the post much shorter when you have to scroll PAST the post to get to other posts after it.

I love the guidelines! Keep the "clean" up! :)
 

Evanski

Raccoon Lord
Forum Staff
Moderator
is it okay if I use a mixture of all 3 indent styles? Or should I practice indenting more?
 

FrostyCat

Redemption Seeker
is it okay if I use a mixture of all 3 indent styles? Or should I practice indenting more?
You can (and should) practice reading and writing all 3 styles, especially if you will be collaborating with others or posting on forums. But in actual project work, pick one and stick to it. For existing projects, keep using the one that it started with unless it started without one.
 
Last edited by a moderator:
Nice guide! I didn't realise there were names attached to the style conventions. While I've always been a sucker for Allman, I've also had an appreciation of the compactness of the K&R style, but never used it because I didn't like the brackets not being aligned to another bracket. Discovering that these conventions had names prompted me go look them up wherupon I discovered more standards. Some of which I had never noticed before. In particular one called Ratliff looks pretty neat because it has K&R style of the top bracket but also gives the bottom bracket something to be aligned to. I might start using it. Learn something new every day. Thanks :D

Update: So it turns out that using Ratliff style for a week did wean me off Allman, but had the unexpected side effect of making me prefer K&R. lol
Is there any style convention suggestions like prefix _var = 5 or
Code:
 my_var
or more importantly, camel case:
Code:
myStringBuffer
 

otterZ

Member
Really helpful info. Will try to follow these guidelines. I didn't even know I had adopted Allman style coding. Interesting that there are different types. Thanks for this.

Not sure what TLDR cards are, an internet search took me to this web page, which isn't helping lol. Are they summary cards? As in people summarising the gist of what a function should do without looking at all the details in the manual and spending time to get to know how it actually works? I'm guessing?
 
Last edited:
Not sure what TLDR cards are
A somewhat whimsical way to describe not reading the manual at all. "Throwing TLDR cards at it," as in stating, "too long, didn't read," regarding the manual's helpful, relevant pages.

@FrostyCat I suggest changing the code tags to code=gml and recommending others to use the code=gml as well, since Xenforo supports syntax colouring for GML now.
Agreed!

(Not as much a necrobump when @Evanski's pinned Programming thread gets updated to link this old banger.)
 
Top