• Hey Guest! Ever feel like entering a Game Jam, but the time limit is always too much pressure? We get it... You lead a hectic life and dedicating 3 whole days to make a game just doesn't work for you! So, why not enter the GMC SLOW JAM? Take your time! Kick back and make your game over 4 months! Interested? Then just click here!

Comment Convention: Addressing Teammates

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:

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
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:
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
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
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)
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:
  • 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
Here's about the closest I've come to... (I do thank TheUltimate for bouncing back and forth with me on this -- and tolerating my constantly shifting back and forth on this particular issue!)

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.
Seems simple enough, but replying becomes an issue. Should be simple, right? But no, not yet:
  • 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
    ...but that seems overly long for a simple "okay" / "me too" sort of comment, eh? Shrinking:
    Code:
    scr_some_great_code(); //:FOO//@PKB //~ optimized, delete if agree
    ...ugh, again, to me, this is inefficient, sending the ball to different courts so much and removing the original comment.
  • 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!
That last basic idea is what's stopping me from feeling like I've fully fleshed this out in a way which should satisfy all parties: readable, easy to type, easy to search, not confused with other readings or searches, etc. Here are a couple of the ideas I've mulled over which I actually like:
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!
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...
Code:
scr_some_great_code(); //:PKB//@FOO //:FOO//←PKB //~ could you optimize your script for xyz reason? thanks!
...although it's too early (without actual use yet) to know for sure.

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.
All righty then! Discussion-wise, what are some of your favorite comment conventions? Question-answering-wise, do you have any advice (or conventions already in use) for addressing teammates (including self) from within comments? (Or, for that matter, what external tool(s) do you use to systematically link teammate-addressing to specific parts of the code/project?)

Many regards, O Community for the Maker of Games,
Bob $:^ ]
 

jo-thijs

Member
Your method looks way better than what I was doing, so I don't think I'll be able to make many good suggestions,
but I did want to say a couple of things.

First of all, when I was compaing:
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
with:
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)
my first thought was that the latter was more focused on a commenting system in teams,
whereas the first one looks more like a comment system to organize things for yourself.

You later confirmed this in your post, so that might mean something.

As for the difference between //~, //` and //?, my guess would be that:

Code:
//~ is for when you've written code that leaves a bad taste in your mouth and you either want to warn others or ask others for help
//` is for when you feel smug and want to show someone's code is inferior to what you can do
//? is for when someone confuses the hell out of you with their code and you make an attempt to change that.
Personally, I don't like the ` and the ← symbol because they feel like too much of a hassle to type and they feel like they lack support.
The arrow symbol isn't even an ascii character and might not always be saved correctly.

As for flagging someone's read and agreed some comment has served is purpose and can be removed,
They could change the //@NAME to //@NAME* if they were addresses and they could otherwise add //@NAME* after the comment.
 

Yal

🐧 *penguin noises*
GMC Elder
I prefer stating the purpose of a comment over using some cryptic symbols for it (e.g. //TODO for unfinished code, with some descriptive text about what remains... possibly by whom as well, e.g. //TODO YAL). It's easier to remember and it can be easier to search for these tags if you want to find stuff without manually reading through code (! and ~ both are operators that would return false positives), and IMO it's faster to type as well since you don't need to move away from your normal letter key hand positioning/home row/whatever.

I also think all hacks need a clear labelling, especially if they have a purpose that could be ruined if someone thought it was a typo or bug and 'fixed' it. Example,
Code:
for(c = c;c < listSize;c++){//Continue previous loop
 
P

ParodyKnaveBob

Guest
Thanks for the input, @jo-thijs. (And the candor! When I saw you'd responded, I certainly didn't expect your surprise "better than mine" answer, ha! Color me flattered, heheh.)

Fwiw, Ult's suggestion was only in addition onto my symbols. In other words...
//!
//~
//NEW
//OLD
//DEBUG
//IDE vX #X
...plus...
//`
//?
...meaning things are still pretty semantically organized, but with some additional flags for teams in particular. (Just saying, it's like, "plus teamwork" because it still has all the other tags -- as opposed to "focused" per se via removing the NEW,OLD,etc. tags as I accidentally insinuated. Sorry about the confusion I caused.)

But again, yeah, I figure //` and //~ are too similar in meaning and //? can be meant just as well as //~ [comment about not understanding] since any code that the team can't read really should be cleared up anyway, preferably in self-documenting code, but of course sometimes needing explicit comments aside.

~~~​

Frankly, I originally used...
//!
//~
/*!
/*~
//NEW!
//NEW~
/*NEW!
/*NEW~
...etc., but I found having to perform and cross-reference multiple searches just to find all "NEW" tags (for example) eventually got too long and drawn out. Otoh, search //NEW and get all in one list? (And the IDEs I've used, including GameMaker: Studio, will show some context for each search result, meaning one can see in the list if it's...
//! //NEW
...or...
//~ //NEW
...or...
//NEW //!
...or even...
//! - THIS BREAKS THE MAIN SUCH-AND-SUCH SCRIPT - //NEW - try such-and-such right here instead
...and neither the order nor the proximity need be exact and/or accounted for in the search.

That brings me to your suggestion (again, thank you for it):
//@NAME
to address a person, then that person changing it to
//@NAME*
Two issues: 1. I can't use a constant string to search for "all comments where any addressed person has flagged it back" because there's a variable breaking between enclosing symbols. 2. I see you went with "the person who got addressed flags self." That's a valid approach, I'm sure, (and in fact if these two approaches could be simply simultaneously combined, all the better, eh?) but I really want to see "the person who did the addressing gets flagged" so that at any time a person who addressed anyone can review when it's deemed done...... and yeah, I definitely see the advantage of what you said, so that at any time a person who got addressed can review if it's been reviewed by the addresser yet. Gotta think about this more.

Fwiw, before going super modular and making all flags start with //, (and after realizing that accountability and light dialogue could be important,) there were attempts to directly connect names. Stuff like //BOB>>>FOO and eventually //BOB<<<FOO, although the >> << conflict was of course annoying, along with the attempt to secure modular searches. I'm truly shocked that I haven't found even one resource online about this -- and I've been searching on and off for over a year at this point. $8^ | $8^ | Like, nobody has standardized or even publicized personal ponderings anywhere in the major coding discussion circles from Stack Exchange to Usenet?? Just wow. (If it's out there, it's hidden pretty nicely...)

//@FOO//PKB
...is interesting. It's short, clear ( //@TO//FROM ), allows : to be reserved if need be, allows easy searching of names addressed or addressing -- but doesn't allow for "show all times anyone generically addressed someone else" (like in the above) (because // is generic by itself without the variable adjacent names ... however, I'm realizing now, any generic address could be found via //@ anyway! hmmm $:^ J that's hopeful...).

I'll come back to this...

~~~​

Thanks for your feedback, too, @Yal. While searching for (non-existent/non-widespread) teamwork commenting standards in the past year, I did come across some people lauding the //TODO and //FIX flags. Fwiw, I certainly don't want totally arbitrary symbols. I came up with //! because that ! just screams alert, warning, look here! $:^ ] And then, while I realized sometimes I wanted to flag my attention to come back to work on something (and let it be searchable) but it's not an emergency, the ~ just gave me a visual feeling of "eh" [stick hand out, palm face down, fingers spread a little, wobble hand a little] .. more wishy-washy, so to speak, than the ! importance of fix/improve/build asap, or as Ult put it, before release.

(Meanwhile, your //TODO YAL doesn't directly address the issues of having a simple flag for "I'm done if you are" -- which could be a lot less verbose than more-and-more back-and-forth confirmation questions about everyone being satisfied.)

That said, I agree with jo-thijs about the arrows. Even when I suggested it (long before this thread), I gave the caveat, it's not simple to type. $:^ \ That goes for the ` symbol, eh? Since I just hit the key in the upper left corner (between 1 and Tab, and under Esc), it's easy to forget others may need to press ` then Spacebar or some AltGr combination to get it.

However, the hope against false positives is that it'd be like any other overloaded operator: + doesn't get confused with ++ in general, right? (We'll just pretend GML 1.0's = vs. == controversy doesn't exist. $;^ b heheheh) I for one type a -= b; and a = -b; to visually distinguish. Likewise, | || and [| retain distinct meanings, as do [ [| [# etc. My experience in eying code+comments and using search features is that //! and //~ (surrounded by whitespace!) remain entirely distinct from the !operator and ~operator, especially with code colorization -- and even commented-out official language operators I haven't personally confused with unofficial comment "operators," although I clearly can't speak for others (since this is such a silent topic online in general, ugh, plus my own minisculity of programming-team experience).

~~~​

Okay, let's postulate...

//@TO//FROM

...is the golden ticket. (Brainstorming out loud here.) What's the golden "I'm done if you are" flag? Keeping in mind...

//@ is searchable for all addressees
//@TO is searchable for all times the person "TO" gets addressed
side-effect: in the current line of thought, TO// is also "TO" getting addressed... this fact might be harnessed somehow
//FROM is searchable for all times the person "FROM" addresses someone
TO//FROM is searchable for all times the person "FROM" addresses the person "TO" (also important! although I might've left this out until now, sorry)

//@TO//FROM//^

//@ retains its function (i.e. unique, nmemonic, semantic meaning; searchability;
//@TO retains its function
TO// retains its side effect (which results in forward compatibility with any new nomenclature)
//FROM retains its function
TO//FROM retains its function
FROM// when searched does mean the person "FROM" is getting addressed (albeit in a very specific way)
FROM//^ when searched completes the type of address, "the person whom FROM addressed now seeks FROM to confirm and clean up comments"
//^ is searchable for all times an issue is requesting confirmation and closure
//^ can convey a visual "pointing back" meaning (due to forum/e-mail/newsgroup/chat/etc. conditioning over the years)
//^ is as easy to type as a comment and an xor (bitwise) operator -- or an exponent operator, if considering other languages -- however difficult that is
//^ seems to carry less potential cross-language annoyance compared to anything with < or >, such as //< or ~shudder~ //> (lol) considering things like SGML, HTML5, XML, PHP, etc.

Quick made-up tests. (I'll use a kind of lackluster, vague function name just to move it on along.)

PKB writes...

//! scr_handle_spr(); //! this crashes now that we started changing animation mechanics //@FOO//PKB I'll rewrite this from scratch, but I need two good sprites (different number of frames each) to really test with first

FOO finishes two sprites, then marks...

//! scr_handle_spr(); //! this crashes nwo that we started changing animation mechanics //@FOO//PKB//^ I'll rewrite this from scratch, but I need two good sprites (different number of frames each) to really test with first

PKB cleans up the comments...

scr_handle_spr(); //! //NEW currently does not loop, but hey, no more crash $:^ }

PKB finishes the script later...

scr_handle_spr();

FOO writes...

scr_handle_spr(); //! //@PKB//FOO this now interferes with some_other_great_thing() and I don't know why

PKB fixes it, and marks it...

scr_handle_spr(); //! //@PKB//FOO//^ this now interferes with some_other_great_thing() and I don't know why

FOO removes the mark, and writes more...and hmm, there's currently not a way to easily mark one's own comment for immediate deletion other than I guess just stating it in the text...

scr_handle_spr(); //! //@PKB//FOO this now interferes with some_other_great_thing() and I don't know why //@PKB//FOO there's still an edge case with something_such, but I think I found the problem: some_other_such does techytechyblahblah - in fact, yeah, I just fixed it (and noted in the script itself to check for techyblah only when changing blabbytech (instead of in the script) to keep FPS up) - clean comments if ready

PKB cleans up comments again...

scr_handle_spr();

Feels like I could write a much better example, but whatever. I don't want to create artificial problems to fix right now. $;^ } Also, I could see a "mark self comment for deletion by other" tag/shorthand/etc. developing over time if the need arises. Doesn't seem like a crucial, pivotal-moment bridge to cross, let alone before getting there -- although a succinct solution would still indeed be nice.

~~~​

Now, let's see how much sense this made. $E^ J About to fall asleep again. ~exhale~

Bob
 
T

TheUltimate

Guest
Aha! I've been summoned to this topic!

After rereading this, I think we're making it too complicated. We should ask
  • What's the advantage putting it in the code versus an external file? For example //! is something we need to resolve, so being able to search for and fix every last instance in the code is important. In contrast, the game's in development and it's expected lots of code in lots of places will be added, so we make //NEW an external changelog.
  • Are we gonna archive it? Comments to teammates should be temporary (to keep the search results up-to-date) and I fear addressing each other in the code is gonna end with big, hard-to-find walls of code we never erase, which drowns out the comments documenting how the code works.
Anyways, some ideas:

I always liked the idea of searchable comments, so I suggest we keep those to comment on the state of the code.
Code:
//! SERIOUS ISSUE: BROKEN, MUST BE FIXED, ETC.
//~ more optional issue: good place to add a new feature, or good candidate for optimization/refactorization
//OLD obsolete, only keeping for reference until it's entirely replaced
//WORKAROUND temporary-I-hope workaround (or even removed feature from GMS)
Comments to teammates could be external with a tag in the code. Then, we have a Word document with the tag as a header, and the discussion under it. It fits both our criteria: It's searchable, you can name people, it's easy to delete from the code, all the discussion is all in one place, and the discussion is archiveable.

In the code
Code:
scr_some_great_code(); //:Tag#1
In the document
Code:
Tag #1
PKB: could you optimize your script for xyz reason? thanks!
Ult: finished
 
E

Ethanicus

Guest
I think the //THING system makes the most sense, when combined with the //@NAME system.
Example:
Code:
scr_thing_that_does_stuff() //FIX//@JOE: Doesn't work properly, makes things not do stuff. //@MOE//&JOE: Works now?
So JOE could search "//&" and find any answers, or "//&JOE" for answers to him specifically.
 
P

ParodyKnaveBob

Guest
Howdy, Ult, $:^ ]

Replying to you will be a little different because I mainly want to respond in a universal way for the sake of the topic at large -- but also we're already working on Julius Dragonslayer, and it's a given that any one person's strict standards might need to bend or break the moment teamwork enjoins. Nevertheless, I'll try to keep this post simple and not splitting off into (too many? lol) branches of thought. $:^ b

re: complicated
Although I'm analyzing this into the ground (like I do so many things), my purpose is to make a simple system -- that's also robust, and even adaptable where need be.

re: advantage of in-code vs. external
Interesting concept. I'll come right back to this in this post! $:^ ]

re: archive
I might not have made it clear up above, but the point of teammate tags was certainly to be temporary until it's handled. You and I have the same fear about walls of text (especially when one or more teammates are prone to wordmasonry! $E^ D lol). However, when asking the question that way, "Are we gonna archive it?" there is advantage to that, too. (Fwiw, SCM such as SVN helps with archiving comments on each commit.) I'll come right back to this in a moment, too.

re: state flagging comments (status tag comments?) (w/e heheh)
Indeed, searchable comments rock super hard. Looking at your new list...
//! //~ //OLD //WORKAROUND (no //NEW nor //IDE nor //DEBUG)
  1. I practically assume you'd still want //DEBUG ..but maybe I'm wrong? ..oh! how weird, I didn't even type //DEBUG into my topic-starter list! (even though I illustrated it right below it, ha!)
  2. I still see //NEW as a valuable organizational placeholder marker. This is the exact spot where XYZ shall go; this event should be reserved for ABC (due to EDF modular-perhaps reason); or even, this //! is broken or fragile, sure, but the reason why is that it's still //NEW in the first place - a lot of meaning gets packed into that one little word, at least for me, especially when paired in some contexts with //OLD to immediately differentiate (such as when in the middle of refactoring a gigantic code chunk, pointing at pieces being renamed, being split off into other events or scripts, etc.).
  3. //IDE is important for me b/c it says "you can practically ignore this wonky code here until the IDE's fixed. This can mark any commented-out proper code (which currently fails) and save it for later. This can mark workarounds put into use for now. This can document ("once and for all") where the bug's being tracked for future replacement, minimizing repeat checking over time. ~~~ As for me, and concerning GM, there've been weeks I've spent much more time on Mantis than on the GMC, reporting bugs, commenting on others, etc. Even if no one else in any-given-team-I'm-in cares about //IDE, it gives me peace of mind, for if nothing else knowing "this ugly, inefficient hackneyed 'solution' is NOT my/our fault."
  4. Because of //IDE (not to mention //~ or even //! ), //WORKAROUND seems completely covered already. $:^ ]
Therefore, my own personal list of flags (or tags or w/e) still remains...
//! //~ //DEBUG //NEW //OLD //IDE
...although adjustments for teams would be understandable if need be, especially if there's already an established system, and I'm joining in the middle. (Which, in JD's case, I'm essentially joining in the middle, but I don't think any of us would say there was a comments system.)
//! //~ .. severity
//DEBUG //NEW //OLD .. core nature of temporary stuff
//IDE .. 3rd party reliant $:^ [

Now, all that said, here's the part where
I come back to those other bits from earlier.

Concerning archiving and //NEW stuff: Once I started writing changelogs (published in the "JAM! LIVE! RANDOM!" game and the Time'lign utility), I started adding items to said changelogs once I could remove the //NEW temporary issues, thereby serving both temporary-in-code and external-archive needs.

But okay, the super-fantabulous moment I've been waiting for: You might have just solved the problem. $:^ b
Obviously, this idea's like in untested-brainstorm-pre-alpha stage, but using in-code temporary tags to point at in-progress-and-then-archived-when-finished discussions? SUH-WEET. Questions arise of course...

What does the tag look like? Using //:XYZ for some tag XYZ is interesting, but should it be paired with any //@NAME flagtaghagbagthang? (lol, at-mentions and hash-tags ... //@Name //#Topic ... LOL ... maybe, maybe ... but naaaah, nevermind, # is already used as a comment starter in various languages, meaning ##Topic isn't anything like discernable, and people would surely be using ###### HEADER ###### kind of stuff already .. okay, //@ and/or //: looks feasible so far..)

What purpose(s) does this flag serve?
  • a 1-to-1 correlation between that line/chunk of code to that external discussion?
  • a multi-tag system, letting different comments be umbrella'd under one or more discussions?
  • a 1-to-multi? a multi-to-1?
The answer to that question relates to this: Should teammates be tagged -- or at least taggable?
  • should it be that all relevant teammates should remain flagged? - despite granting personal searchability within code, this increases comment maintenance, thus probably no, esp. since the archive intends to keep this searchable too...
  • should it be that some teammate(s) might get flagged just to get their attention? - again, code-comment maintenance - if designed well enough, the tag-list archive should be able to do this, too
  • should it be that teammates do NOT get flagged in code comments? - the searchability is awesome, but a simple //:tag really probably could suffice
(I really am essaying this out loud as I go, although I have erased a couple noisy dead ends, heheh.)
Code:
scr_some_great_code(); //:1
scr_some_mediocre_code(); //:2
scr_some_wretched_filth(); //:2
Simple indexing could easily get duplicated by accident.
Code:
scr_some_great_code(); //:160930-064307
Time-stamping by UTC -- just saying, this is the moment I looked at the clock when I originally marked this -- has little chance of conflict, but isn't exactly pretty.
Code:
scr_some_great_code(); //:optimize
Using such //:words can help "tag"/categorize, which can be good for nmemonics but bad for potential mis-remembering, and can also be bad for uniqueness (like again accidental duplication .. or simply so-close-it's-confusing).
I just now considered
Code:
scr_some_great_code(); //:DOC
(or something similar) and then
o_ctrl_main, Room Start Event, action 1, line 5
...but quickly realized how atrocious that is since code could not only move lines, actions, events, or objects, but entire resources (from object to timeline, from script to Room Creation Code, etc.) Meh.
Now, once it's in the "tagged discussion document," yeah, easily searchable:
some tag thing - @Ult @PKB - //WIP
PKB: Ult, what does this button do?

other tag thing - +PKB +Ult - //DONE
Ult: PKB, I fixed the W/E mechanic here, but there's some XYZ conflict with your new WVU script
PKB: cool thanks re: fixing - and okay, I'll look at it
PKB: silly typo when handling an edge case, finished
  • ...so like, in this made-up example, I made //WIP and //DONE distinguishably searchable ... although that might not be necessary ... there could be separate WIP and DONE files, actually ... so many options to consider
  • also in this example, I semi-arbitrarily made +NAME different from @NAME just so one could search for names in WIP vs. DONE pretty easily, but again, actually, keeping separate WIP vs. DONE files could alleviate that problem anyway...
I really, really wanna like this tag system. I believe the main issue is just what method of tagging it should take... Anyone? Anyone? Beuler?

.......and then there's the option to say, "forget normal documents, use Trello or something!" $:^ } (That's what happens when you go external -- although it could be argued, everything could still be kept inside GM by using the old "Game Information" help.rtf or an uncalled script filled with nothing but comments -- although the fact that those comments would show up in Shift+Ctrl+F searches would be simultaneously convenient and annoying.)

I'd better stop here while I can pretend I'm ahead. $E^ ]

Bob

P.S. @Ethanicus! Thanks for your input, too. I'm glad you can find something that works for you -- //FIX, //TODO, etc. For reasons listed above (archiving, walls of text getting in the way of code and "real" comments), I just don't know anymore about trying to outright converse within the code. And ah, I see you'd prefer @ to be the author instead of the receiver? Personally, I'd find that confusing since @ reads "at" (and beyond e-mail, "at-mentioning" has been a convention in heavy, widespread use for years now, primarily due to Twitter -- you'll notice how I mentioned you in this post $E^ J heheh).

P.P.S. Thank you, too, @NightFrost. The issue isn't taking discussion already going on in external services and bringing them into code comments. The issue is handling very specific code issue discussions in lieu of any of those external services being used (and we're not talking just general discussion about progress, but again, that which pertains to very specific points in code). However, that said, I'm inclined to agree with you that tools specifically designed for some of these issues could in the long run be much, much better -- even if it's Trello-and-nothing-else for something small like a jam, whereas setting up Mantis could seem like overkill -- but ...... in so many words, broadly speaking, it's not always easy to get all teammates mentally onboard with beginning so many new adventures simultaneously, and in the event everyone's onboard, one or more team members might feel unduly pressured to learn more and more systems when the rest of life already has a crunch on one's time. Trying to figure out team comments is an exercise in compromise -- for better or worse. Meanwhile, I can't help but think that discussing the various caveats of teammate addresses and answers is already slowly gravitating toward the notion of "use an external tool already built for that exact purpose."
 
E

Ethanicus

Guest
P.S. @Ethanicus! Thanks for your input, too. I'm glad you can find something that works for you -- //FIX, //TODO, etc. For reasons listed above (archiving, walls of text getting in the way of code and "real" comments), I just don't know anymore about trying to outright converse within the code. And ah, I see you'd prefer @ to be the author instead of the receiver? Personally, I'd find that confusing since @ reads "at" (and beyond e-mail, "at-mentioning" has been a convention in heavy, widespread use for years now, primarily due to Twitter -- you'll notice how I mentioned you in this post $E^ J heheh).
Whoop, you're right with the "@" thing! Got that backwards.
I do tend to work alone, but being a forgetful person many times makes me work as if I were a team. XD
 
R

RealsLife

Guest


Well I read some parts :p, I agree with NightFrost there are awesome tools for teamwork. I don't see the use for small teams to have tons of comments everywhere with to many useless info. Large teams won't use game maker studio so... I'm done :x.
 
R

renex

Guest
I have a very simple protocol.

// code comment
//@ to do mark

and then I use devlogs.

Code:
* this is done
* this is also done

! the thing that's partially working
! the other thing that's half done
! i did this already but forgot to test

- some task is pending
- horrible bug needs fixed

? not sure i'm doing this
? is this really a bug

x not doing this
This way I can either search for //@ or look at my devlog. When I work with other people, each developer gets their separate devlog.

Working fine for me for over 5 years.
 

sylvain_l

Member
You make really a good point stating the importance of being wise with comment convention, but
+1 for @NightFrost , there are plenty tools around for any budget and usage to do most of it better.

In dreamland we should just use what fit. IMHO gathering code with discussion that don't belong in code is just a bad idea.

That don't prevent having some good guidlines about communication and teamwork :)
but KISS please (keep it simple stupid, works for code, but also for commenting)

For a start: don't make it overcomplicated with a full list of unclear char
Code:
 //!?whywhywhy#%@coder1:blabla@coder2:*£blabla  yeh I'm the evil comment
comment should enlight code, not make it more confuse

most decent solution have tagging, category and such organizing feature, allowing formatting, attachment and so on and try their best to handle branching & merging, task&bug management, etc, do you really want to reinvent the wheel or go far without any?

I'm really curious about how your convention is going to work with branching/merging. Imaging having that thread about commenting convention on an open project with random contributor into a code file o_O ! (sorry lame argument:oops:)

IRL
I'm lazy coder, so most of the time. I start with good intention, making the first commit with fossil or git... and then things go wrong, and worst :eek:
 
Considering every programmer does things differently and has their own ways of approaching issues, I think this is something that will be different and specific to each and every team.

The best option is to probably discuss it with your team and see what they're comfortable with. If anyone told me about a system where I would be referenced in code, I would immediately tell them no and that we should use a third party application to handle it with agile methodologies. I feel like by commenting in for tasks and references loses its sense of documentation, since it would be convoluted to organize large-scale projects.

However, and most importantly, it would remove the sense of a record. Comments are not a proper way to record work that needs to be done or has been done.
 
P

ParodyKnaveBob

Guest
Hey, thank you, @sylvain_l and @Online Handle, for your input.

Fwiw, at this point, @TheUltimate and I have been using Trello all this month -- first time for either of us -- and it's remarkable (with the increasingly normal caveat of "you have to be online all the time for it to work"). So far we've relatively blazed through other preliminaries (game brainstorming and solidifying, coding standards, etc.), communicated pretty well with newly adventuring into GM+SVN, and finally started comment standards just yesterday or so. Especially now that I see there's still interest in the topic of comment standards, especially as it relates to teamwork, I'll make sure at some point to report back here our findings.

Regards!
Bob $:^ ]
 
Last edited by a moderator:
E

Ethanicus

Guest
Hey, thank you, @sylvain_l and @Online Handle, for your input.

Fwiw, at this point, @TheUltimate and I have been using Trello all this month -- first time for either of us -- and it's remarkable (with the increasingly normal caveat of "you have to be online all the time for it to work"). So far we've relatively blazed through other preliminaries (game brainstorming and solidifying, coding standards, etc.), communicated pretty well with newly adventuring into GM+SVN, and we finally started comment standards just yesterday or so. Especially now that I see there's still interest in the topic of comment standards, especially as it relates to teamwork, I'll make sure at some point to report back here our findings.

Regards!
Bob $:^ ]
How's Trello working out for you? Just out of curiosity. Is it worth it on the free version?
 
P

ParodyKnaveBob

Guest
How's Trello working out for you? Just out of curiosity. Is it worth it on the free version?
it's remarkable
$:^ J

The only actual shortcomings off the top of my head: 1. No option to automatically show online status -- although we've made a system of adding/removing one's own name to a dedicated upper-left chat card to manually show online status. 2. No way to move a comment on a card to another card; if it's that important to move, you have to c/p your text and delete the old comment; therefore, you really need to compartmentalize your discussions.

Otherwise, go check out videos on it working. Also, just play around viewing Trello's own dev board using different filters and such; it'll give you an idea for UI feel **and speed**.

I hope this helps,
Bob
 
Top