P
ParodyKnaveBob
Guest
Howdy, all, $:^ ]
I've been using GM for awhile now, but this is my first post asking a question, and I hope it's in the right forum. Since my riveting post introduction totally demonstrates I'm an absolute expert, you can obviously tell my problem is way advanced. Addressing teammates from code comments -- is this even possible in GameMaker Studioes?!
(Lol. C'mon! For real, though, my first question for the Q&A/Programming forum, thus I gotta have some fun with it, right?) Okay, seriously, although I do have a pointed question mixed in here, perhaps this thread could serve as a hub for our comment conventions, too. Note: my (rather long) post assumes for clear, self-commenting code (despite my hackneyed written examples); if you're unfamiliar, go look up self-commenting or self-documenting code! Anyway, as for actually using comments, here's what I have so far... (I apologize in advance for any unclarity. I've been writing/editing this post for hours now...)
Throughout my years programming in various languages, I've gradually developed some commenting conventions, generally translatable to any language. In GML, it looks like so:
You can mix and match the flags as needed. (You'll note, my post isn't really dealing with script headers or even multiline comments. You can talk about them in the thread if you want, and I very well might add my two cents worth, but for now, I'm just dealing with flagging/categorizing code using comments when appropriate.) Here's something of an example; fwiw, the quintuple-slash comment allows for //! to appear in the action list along with the rest of the name.
Keyboard Pressed <Escape> Event:
Execute Code Action:
Now, that feels like a pretty bad example up above b/c I just slapped it together off the top of my head instead of using a real-world case, (thus some of it I might not actually use exactly like that,) but it hopefully gets the gist across: By doing this, not only do certain symbols catch your eye while in the code, but also you can search for any categorized issue. Ctrl+Alt+F, and suddenly you can get a centralized list of every //! to fix or //NEW to add/finish or //IDE to check on the next GM update. Good stuff. $:^ ]
Fwiw, @TheUltimate has discussed my nomenclature with me, which has furthered my system, and I hope she doesn't mind my presenting some of her own suggestions, especially since I'm going to give my arguments against, too. $E^ P
So, //! keeps its essential meaning, but //~ and //` ... it's hard for me to see any substantial difference between the two. I'll say //? has some potential, but between using a teammate flag or a //~ this isn't clear and therefore could be refactored or better commented flag+note, //? might therefore be too redundant as well. So far, it seems to me, //! and //~ are the only two real needed flags for fixing/improving/adding/etc. things.
Thing is, I've almost always worked solo. Somehow, anytime my job has included "Webmaster" or any such similar, I've been alone. And then, I joined a team or two. I quickly shared my conventions, and in the first team I realized we needed to leave little messages for teammates sometimes. I came up with //NAME (such as //PKB (or //BOB if preferred) and the like). However, this opened plenty of questions over time. In some cases, a message needs to come from someone vs. be addressed to someone; doing both is likely best -- accountability for who-sent and ownership for who-receives (even if "ALL" or "ANY" gets used). Also, what if you wanted to collectively search for all messages sent to anyone to see what all's still an outstanding issue as such?
I understand that Source Control Management solutions (such as SVN, Subversion Control,) or bug trackers (like Mantis) can answer this to an extent, but to have little "hey you!" flags in the codebase itself has the advantage of remaining centralized instead of relying on yet another outside source (which sometimes can overwhelm a small team, especially in a hobbyist setting such as for a game jam).
I've tried to work out a system that allows for the following, but I haven't been satisfied yet:
Let's say I'm PKB and my teammate is FOO. (Not like foo/bar, but I PITY DA FOO WHO WORK WITH PKB.)
To make sure we're not lost here: PKB sent the message, FOO attempted to fulfill the reason for the message, and FOO has left a marker to request PKB delete the comment if satisfied.
The first is pretty clear and allows for //:PKB//@FOO//@PKB//@FOO chains to go backward (although that loses the //: flag unless it's doubled up like //:PKB//@FOO comment1 //:FOO//@PKB comment2 //:pKB//@FOO comment3 (or even ordered as comment3..1) erg) before hitting a //← flag. Nevertheless, even neverminding the chain potential, //:PKB//@FOO//←PKB could possibly be improved simply by going //:PKB//@FOO //:FOO//←PKB before the final comment...
The second is much shorter, yaaaaay, but it feels like it loses some clarity somewhere, plus it definitely loses the original //: flag, which definitely means some functionality gets lost.
Clearly, we don't want "the comments section" to become a whole forum thread in the code editor, y'know? Nevertheless, communication is good, and closure on the communication (especially in this case so that unnecessary comments can be removed!) is important.
I'm starting to land on...
...although it's too early (without actual use yet) to know for sure.
Concerning symbols...
Many regards, O Community for the Maker of Games,
Bob $:^ ]
I've been using GM for awhile now, but this is my first post asking a question, and I hope it's in the right forum. Since my riveting post introduction totally demonstrates I'm an absolute expert, you can obviously tell my problem is way advanced. Addressing teammates from code comments -- is this even possible in GameMaker Studioes?!
(Lol. C'mon! For real, though, my first question for the Q&A/Programming forum, thus I gotta have some fun with it, right?) Okay, seriously, although I do have a pointed question mixed in here, perhaps this thread could serve as a hub for our comment conventions, too. Note: my (rather long) post assumes for clear, self-commenting code (despite my hackneyed written examples); if you're unfamiliar, go look up self-commenting or self-documenting code! Anyway, as for actually using comments, here's what I have so far... (I apologize in advance for any unclarity. I've been writing/editing this post for hours now...)
Throughout my years programming in various languages, I've gradually developed some commenting conventions, generally translatable to any language. In GML, it looks like so:
Code:
// some plain ol' comment for whatever reason
//! SERIOUS ISSUE: BROKEN, MUST BE FIXED, ETC.
//~ more optional issue: good place to add a new feature, or good candidate for optimization/refactorization
//NEW unfinished (or even placeholder) feature
//OLD obsolete, only keeping for reference until it's entirely replaced
//IDE vX.X.X (#XXXXX) temporary-I-hope workaround (or even removed feature) due to GM version vX.X.X, documented in Mantis bug #XXXXX; only keeping until YYG fixes of course
Keyboard Pressed <Escape> Event:
Execute Code Action:
Code:
/////! //NEW Pause Game, Show Menu
/* //DEBUG
if (keyboard_check(ord("D"))) {
show_debug_message(DEBUG_str_making_up_nonmodular_junk_now_to_show_different_comments);
exit;
}
// */
show_message("Paused!"); //! NEED TO BUILD REAL PAUSE SCREEN
//! //NEW - CALL MENU AFTER PROGRAMMING IT $F^ J
Fwiw, @TheUltimate has discussed my nomenclature with me, which has furthered my system, and I hope she doesn't mind my presenting some of her own suggestions, especially since I'm going to give my arguments against, too. $E^ P
Code:
//! important (broken or slow: should be fixed before release)
//~ preferable (could be refactored, optimized, polished, etc.)
//` improvements (suggestions for the code)
//? questions (questions about how something works)
Thing is, I've almost always worked solo. Somehow, anytime my job has included "Webmaster" or any such similar, I've been alone. And then, I joined a team or two. I quickly shared my conventions, and in the first team I realized we needed to leave little messages for teammates sometimes. I came up with //NAME (such as //PKB (or //BOB if preferred) and the like). However, this opened plenty of questions over time. In some cases, a message needs to come from someone vs. be addressed to someone; doing both is likely best -- accountability for who-sent and ownership for who-receives (even if "ALL" or "ANY" gets used). Also, what if you wanted to collectively search for all messages sent to anyone to see what all's still an outstanding issue as such?
I understand that Source Control Management solutions (such as SVN, Subversion Control,) or bug trackers (like Mantis) can answer this to an extent, but to have little "hey you!" flags in the codebase itself has the advantage of remaining centralized instead of relying on yet another outside source (which sometimes can overwhelm a small team, especially in a hobbyist setting such as for a game jam).
I've tried to work out a system that allows for the following, but I haven't been satisfied yet:
- modular with other //flags
- shows the addresser (probably must be included if addressing)
- shows the addressee (probably must be included if addressing)
- allows for reply and/or "I'm ready to delete if you are" flag
- allows searching for it without conflicts with any other search
Let's say I'm PKB and my teammate is FOO. (Not like foo/bar, but I PITY DA FOO WHO WORK WITH PKB.)
Code:
scr_some_great_code(); //:PKB//@FOO //~ could you optimize your script for xyz reason? thanks!
- Separate from //~ thus modular.
- Search //: to get all addressers (without any URL string search conflicts).
- Search //@ to get all addressees (without any [@ accessor search conflicts).
- Search :PKB (or //:PKB or PKB// ) to get all times I address anyone. (A little too much redundant functionality perhaps.) Sorry if this says pKB. Fighting forum smilies here.
- Search //@FOO to get all times FOO gets addressed.
- If FOO optimizes and feels it's done, then what? Delete the addressed comment and good to go, right? But wait, what if PKB disagrees with FOO's conclusion? The comment really should stay until all parties agree it's taken care of.
- So then, FOO leaves a comment:
Code:scr_some_great_code(); //:PKB//@FOO //~ could you optimize your script for xyz reason? thanks! //:FOO//@PKB finished
Code:scr_some_great_code(); //:FOO//@PKB //~ optimized, delete if agree
- What would be great is a way to keep the comment exactly as-is, but flag it for "I'm done - are you done, too?" ..and still keep all the attributes I listed above: clear and unconflictably searchable. Basically:
Code:scr_some_great_code(); //[slightly modified version of original flag] //~ could you optimize your script for xyz reason? thanks!
Code:
scr_some_great_code(); //:PKB//@FOO//←PKB //~ could you optimize your script for xyz reason? thanks!
Code:
scr_some_great_code(); //←PKB//@FOO //~ could you optimize your script for xyz reason? thanks!
The first is pretty clear and allows for //:PKB//@FOO//@PKB//@FOO chains to go backward (although that loses the //: flag unless it's doubled up like //:PKB//@FOO comment1 //:FOO//@PKB comment2 //:pKB//@FOO comment3 (or even ordered as comment3..1) erg) before hitting a //← flag. Nevertheless, even neverminding the chain potential, //:PKB//@FOO//←PKB could possibly be improved simply by going //:PKB//@FOO //:FOO//←PKB before the final comment...
The second is much shorter, yaaaaay, but it feels like it loses some clarity somewhere, plus it definitely loses the original //: flag, which definitely means some functionality gets lost.
Clearly, we don't want "the comments section" to become a whole forum thread in the code editor, y'know? Nevertheless, communication is good, and closure on the communication (especially in this case so that unnecessary comments can be removed!) is important.
I'm starting to land on...
Code:
scr_some_great_code(); //:PKB//@FOO //:FOO//←PKB //~ could you optimize your script for xyz reason? thanks!
Concerning symbols...
- I tried NAME>>>NAME and <<< (to not conflict with >> or <<) but it's long and annoying to modify.
- As usual, I want to avoid any \ usage for compatibility (i.e. cross-use for other languages and potential use if/when GML 2.0 might give us conventional string escaping).
- You can get » « → ← in Windows via Alt+0187, 0171, 8594, 8592 respectively if you have a number keypad -- otherwise, Character Map and/or a c/p list; different languages might get access a little more easily than others. GM:Next, which YYG has said should be a cross-platform IDE, can benefit from Mac's Option key combinations; I don't recall at this point what Linux users do.
- I suppose # $ % ^ & + = _ - etc. could have some use, although I tend to use an HTML-inspired separator which starts //-- for some headers.
Many regards, O Community for the Maker of Games,
Bob $:^ ]