FrostyCat
Redemption Seeker
Posting code on the Programming Forum:
Do's and Dont's
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
- 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();
}
}
Code:
if (foo) {
bar();
while (baz(a, b, c)) {
qux();
}
}
Code:
if (foo)
{
bar();
while (baz(a, b, c))
{
qux();
}
}
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;
}
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: