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

Discussion in 'Tutorials' started by FrostyCat, Mar 21, 2017.

  1. FrostyCat

    FrostyCat Member

    Joined:
    Jun 26, 2016
    Posts:
    2,624
    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: Mar 22, 2017
  2. rIKmAN

    rIKmAN Member

    Joined:
    Sep 6, 2016
    Posts:
    3,125
    Great guide and completely agree, but sadly people aren't going to read this before posting.

    This should be stickied at the top of every forum.
     
    Bentley and estherfanworld like this.
  3. Kuro

    Kuro Member

    Joined:
    Feb 21, 2017
    Posts:
    237
    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: May 24, 2017
    Bentley and ParodyKnaveBob like this.
  4. Roman P.

    Roman P. Member

    Joined:
    Mar 1, 2017
    Posts:
    186
    Allman for me,

    K&R just looks ugly as it can get, Its prob good if youre aiming to be fast
     
    Bentley, andev, fxokz and 2 others like this.
  5. RichHopelessComposer

    RichHopelessComposer Member

    Joined:
    Jun 20, 2016
    Posts:
    1,149
    Preaching to the choir...
     
    Bentley likes this.
  6. The-any-Key

    The-any-Key Member

    Joined:
    Feb 2, 2017
    Posts:
    1,090
    ALLMAN *clap,clap,clap*, ALLMAN *clap,clap,clap*, ALLMAN *clap,clap,clap*...
     
    Bentley and RichHopelessComposer like this.
  7. FrostyCat

    FrostyCat Member

    Joined:
    Jun 26, 2016
    Posts:
    2,624
    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: May 23, 2017
    Bingdom, Morne, Bentley and 5 others like this.
  8. The-any-Key

    The-any-Key Member

    Joined:
    Feb 2, 2017
    Posts:
    1,090
    Reminds me of my old vb5 days :)
    Code:
    if foo=foobar then
        print "food"
    end if
    
    This is why I use one = instead of == in if statements.
     
    Last edited: May 23, 2017
    RichHopelessComposer likes this.
  9. Kenjiro

    Kenjiro Member

    Joined:
    May 21, 2017
    Posts:
    346
    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.
     
    Khanon likes this.
  10. The-any-Key

    The-any-Key Member

    Joined:
    Feb 2, 2017
    Posts:
    1,090
    Let them come.

    But I also code in PHP, Java script... And they use == :)
     
  11. Kenjiro

    Kenjiro Member

    Joined:
    May 21, 2017
    Posts:
    346
    Not understanding why you'd go out of your way to change your coding style, in that case.
     
  12. The-any-Key

    The-any-Key Member

    Joined:
    Feb 2, 2017
    Posts:
    1,090
    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: May 24, 2017
  13. Kenjiro

    Kenjiro Member

    Joined:
    May 21, 2017
    Posts:
    346
    Can't argue with that :D
     
  14. John Andrews

    John Andrews Living Enigma

    Joined:
    Oct 28, 2016
    Posts:
    239
    Really good tips! I was thinking of doing a tutorial on platformers and now I'll take in count these useful advices! :)
     
  15. computercoder

    computercoder Member

    Joined:
    Aug 13, 2017
    Posts:
    9
    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! :)
     
    ParodyKnaveBob and Ragarnak like this.
  16. Electros

    Electros Member

    Joined:
    Jul 19, 2016
    Posts:
    256
    Think I am the only Whitesmith user here. :(

    Thanks FrostyCat, a good informative post!
     
  17. LlamaTemplar

    LlamaTemplar Member

    Joined:
    Aug 23, 2017
    Posts:
    6
    Wow this is so true.
     
  18. BlackRaw

    BlackRaw Member

    Joined:
    Aug 16, 2017
    Posts:
    6
    a little difficult for me to understand:mad:
     
  19. Kuro

    Kuro Member

    Joined:
    Feb 21, 2017
    Posts:
    237
  20. Evan Malinowski

    Evan Malinowski Member

    Joined:
    Apr 17, 2018
    Posts:
    74
    is it okay if I use a mixture of all 3 indent styles? Or should I practice indenting more?
     
  21. FrostyCat

    FrostyCat Member

    Joined:
    Jun 26, 2016
    Posts:
    2,624
    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.
     
    Evan Malinowski likes this.
  22. RichHopelessComposer

    RichHopelessComposer Member

    Joined:
    Jun 20, 2016
    Posts:
    1,149
    Yep. Allman style for life. It's the only style that doesn't look like a jumbled mess to me. Everything lines up so nicely!
     
  23. Smiechu

    Smiechu Member

    Joined:
    Jul 14, 2017
    Posts:
    268
    You're not the only one. I use it to
     
    Electros likes this.
  24. Electros

    Electros Member

    Joined:
    Jul 19, 2016
    Posts:
    256
    *Gravelly Batman voice* Now we're two.
     
    Smiechu likes this.
  25. FrostyCat

    FrostyCat Member

    Joined:
    Jun 26, 2016
    Posts:
    2,624
    I think you Whitesmith users should be more aware of your most prominent kindred spirit: The Manual itself.
     
    Electros likes this.

Share This Page

  1. This site uses cookies to help personalise content, tailor your experience and to keep you logged in if you register.
    By continuing to use this site, you are consenting to our use of cookies.
    Dismiss Notice