1. Hey! Guest! The 33rd GMC Jam will take place between May 23rd, 12:00 UTC (Friday noon) and May 27th, 12:00 UTC (Monday noon). Why not join in! Click here to find out more!
    Dismiss Notice

GML Documentation for own project?

Discussion in 'Programming' started by Vikom, Mar 15, 2019.

  1. Vikom

    Vikom Member

    Joined:
    Jun 21, 2016
    Posts:
    109
    Hi!
    I'm seeking for others' experience.

    Usually, after some time, my projects turn into a mess, so I guess that writing documentation is not a bad idea.
    Do you have any experience with it? I've tried to write a complex documentation along with programming in LO Writer but after about 5 hours of development, I already think it's not the best way to execute it.

    How do you write it? What do you note?
    I believe it is necessary to list all variables that are not "one use" and probably the main description of every object like what it does/should do.

    I'll be grateful for any good answers.
     
  2. Sabnock

    Sabnock Member

    Joined:
    Jul 21, 2016
    Posts:
    272
    i use both comments, notes and trello.

    all coders should at the very least use // comments in their code.

    i note what the code is for, what variables are for what and the structure
     
  3. Vikom

    Vikom Member

    Joined:
    Jun 21, 2016
    Posts:
    109
    Thank you!
    What structure do you use?
    I comment most of vars in Create and sometimes explain what the following script is for but I have no real norm for it.
     
  4. JackTurbo

    JackTurbo Member

    Joined:
    Oct 19, 2016
    Posts:
    782
    I use comments, verbose human readable naming conventions, trello and various Google docs.

    Google docs is great for things like GDD's, random thoughts and ideas for mechanics or characters/story etc

    Trello is awesome for keeping track of tasks, bugs that need to be fixed etc

    The really big one for me however and I really can't emphasize enough just how greatly helpful I find it is; descriptive naming of variables and scripts.
    This is especially helpful when returning to a system I havent touched in a while. Having a longer variable name or script name to type is a tiny cost for being able to tell what something is doing at a glance.
    Take a look at my attack states for example:
    Code:
        #region //attack state
        case "primary attack":
           script_execute(primaryEquippedWeapon);
        break;
        #endregion
    
    A lot of people would never use a variable name like primaryEquippedWeapon.
    Its so long! Thats so much typing! etc
    But just from that one line of code you know that we are executing a script, held in a variable. Thanks to the long descriptive name we know that the contents of that variable will be a weapon script, that its triggered by our primary attack input and that it isnt the only attack script we can use. There is zero ambiguity about what it is and what it does and that is invaluable on a long term project.

    Consistency is also important and can be applied even to throwaway elements like local variables.
    For example if I always use xx/yy for local variables that relate to x/y coordinates, but instead use ii/jj for simple counters. This also tells me a lot at a glance.
     

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