Good comment practices? How do you comment your code?

Evanski

Raccoon Lord
Forum Staff
Moderator
It seems really simple just say what it does but how do you go about commenting your code?

I kinda spread them all over the place in different ways
GML:
//This creates an array to hold the quick referance name for objects
            _array_quick_obj_names = ["to.","db."];
      
            var _array_quick_obj_names_length = array_length_1d(_array_quick_obj_names);
      
            //This loops through the array checking to see if we typed the quick name in our input
            for (var i = 0; i < _array_quick_obj_names_length; i++;)
            {
                var _obj_quickname_value = array_get(_array_quick_obj_names,i);
                _quick_obj_name = string_pos(_obj_quickname_value,_quick_objname_input);
          
                //checks to see if weve typed what were checking for and if so it saves it and stops the loop
                if ((_quick_obj_name) != 0) //if the quick name is in the input string
                {
                    if ((_quick_obj_name) = 1) //if the quick name is the first thing typed
                    {
                        var _quick_obj_name_found = _obj_quickname_value;
                        i = ( (_array_quick_obj_names_length) + 1 );
But I always run into stuff like
GML:
//WE NEED TO CONSTANTLY BE EDITING THIS
            quick_input_tab = _value+" [";
I have no idea what that means but by my use of caps its important probably

So I really want to know, what is the "best way" to comment your code?
 

NightFrost

Member
I try to record the intent in my comments. In other words, if I were to take away all the code, the comments would still give a clear idea what was happening (assuming loops, conditional blocks etc were somehow implicit for example through tab indents) and theoretically could be used to rewrite the code.
 

Yal

šŸ§ *penguin noises*
GMC Elder
I usually write comments first (and occasionally support them with a bunch of blank ifs, whiles and other control flow structures) to only get my intent across, and once that's done, I start writing actual code with a much clearer idea of what to do (and less temptation to comment the obvious). My workflow when adding new content is very "open a million windows and then fill out one thing at a time until all of the stuff is done"-oriented, so writing comments first during a sort of "just-in-time compilation" planning phase is absolutely necessary to not get lost halfway through implementation and start writing stuff that won't work together.

Also, I've started using searchable labels in my comments: TODO for stuff I'm gonna do later (many text editors will actually highlight this, which is how I found out it's a thing), HACK for things that will break if assumptions are violated (so I have a blame list if something goes wrong in a very inexplicable way), and NOTE for things that could be good to know but which probably won't cause issues and which I'll probably remember. Also it could be useful to add in DEBUG comments for debug code, but I usually delete those things so quickly I find it's not worth the bother (and TODO comments on those things means you've got less searches to do, too). Turns out it's much easier to find stuff if you place checkpoints regularly in your code, it's almost always the "finding" part that's the biggest time sink during code maintenance.
 
Top