ID:153404
 Mar 9 2004, 5:46 pm
|
|
Either this should be here, or Off Topic couldnt decide...or maybe newbie...well i was wondering does anyone comment there own code for like a game if there not going to distribute it or something, like if you happen to take a break and forget what something means, or does?? Because i was trying to decide wheather i should comment, or not...so i decided...i'll ask thy fellow byonders for there opinion
| |
|
Mar 9 2004, 5:50 pm
|
|
DarkView
 |
I find commenting helps stop me from over thinking. If I go at my natural pace I'll just add things the second they come into my mind. If I comment I'll put some thought into everything I do.
|
Well, from what I've read almost anywhere, commenting is generally one of the first things that they try to get you to do. Especially if you read through Zilal's tutorials.
But, really, its up to you I guess. -insert shrug- | |
well thats wat i was thinking but those tutorials were meant to inform, but for your own games and such
| |
N1ghtW1ng wrote:
well thats wat i was thinking but those tutorials were meant to inform, but for your own games and such Comment. Your. Code. In two months when you look at it again, you'll actually know what it does right off the bat(for the most part anyways). If your code is not commented, you'll have to spend time figuring out how it works if you want to change something. Also, if you ever plan on working with another programmer, commenting helps so that they also get a general idea of what stuff does. Now, which is better: /* and */, or // to comment code? :P | |
My TAFE IT lecturer once told me "for every one line of code, I like to see three lines of commenting". I don't believe that's necessary, but just enough commenting so that you get the general gist of what it's meant to do, understand?
| |
If I don't plan on showing it to anyone, I usually give the entire proc a comment at the start explaining what happens.
If it is a long proc I comment a little through it, so I can get the jist of what is happening without reading the actual code. | |
DarkView wrote:
If I don't plan on showing it to anyone, I usually give the entire proc a comment at the start explaining what happens. *Agrees* A fairly short comment at the start of the proc saying what the proc is, what values you should pass to it and what it does. Then occasional commenting of different lines inside the procedure if the line looks like it could be hard to understand in the futire, especially if the line is a suspect of possible future bugs, or a possibly location for improvements. | |
Slipknight wrote:
My TAFE IT lecturer once told me "for every one line of code, I like to see three lines of commenting". I don't believe that's necessary, but just enough commenting so that you get the general gist of what it's meant to do, understand? I comment at about one comment to two lines, and people think I comment too much as it is. Personally, I find that my commenting is just about perfect. Explaining your intentions on every distinct set of actions is a very wise course of action, even if you don't plan on distributing your source. One of the primary killers of code is having to add in new features and finding you have to rewrite things. I know it killed a lot of my old projects. | |
Well, I know that under-commenting has killed a large number of my projects... Hey! All of them! Perhaps that's why I still don't have anything coherent to show on the hub?
-le sigh- | |
N1ghtW1ng wrote:
well thats wat i was thinking but those tutorials were meant to inform, but for your own games and such In private projects I comment the purpose of vars when they are declared (and how assosciative list vars are indexed.) I comment what procs are intended for and what they return, unless they are fairly transparent. (Usually my set desc line in verbs is enough that I don't need to comment the purpose.) Then I comment any chunks of code that I think might require clarification when I come back to it in a month. I'm not as thorough about commenting code for myself as I am about libraries and the like. A few words can clarify a chunk to me that might require a sentence or two for others looking at foreign code. Jon88 wrote: Now, which is better: /* and */, or // to comment code? :P I use both. // if I can squeeze the note within the width that can display on screen. If it's longer, I chop up the comment and use /* */. I also tend to use \ to chop up long commands so they will fit without horizontal scrolling. It's much easier to skim the code and prints nicer. The only problem is when I work on a system in 1024x768 resolution, then move the source to a system with 800x600 resolution. | |
I recently started an old project that i hadn't touched in over 6 months, and i WISH i had commented more. A lot more.
| |
Sometimes commenting helps you organize your thoughts too. Its a bit like writing in a journal, it gives you a moment to stop and reflect on what exactly this stuff you're programming is supposed to do!
I like to comment everything that tends to get confusing. This is the kind of commenting that works for me: <code>// commenting on the proc, how it works, what its for, or // whatever else needs to be said about it. proc/Proc(lala, chicken) while(this) do(this) sleep(time) return value</code> But I hate it when people comment like this, even though I only know about it if they post it somewhere: <code>proc/Proc(lala, chicken) while(this) // keep doing it while 'this' is true do(this) // add the remaining value of 'this' sleep(time) // sleep for value equal to time return value</code></code> Because then it just blurs the comments together... Of course, if you've got a big complicated piece of math in there somewhere, it might be nice to add a comment after it to explain what it does. Or if the proc takes place in several stages, you might divide them up into seperate sections with a few lines in between and add a comment at the top of each. <code>// commenting on the proc, how it works, what its for, or // whatever else needs to be said about it. proc/Proc(lala, chicken) while(this) do(this) sleep(time) // Check to see if there is more to do. more_code++ if(more_code > 5) do(this, again) else dont do(this, again) // Check to see if we're done yet. one_more++ while(one_more) one_more-- if(are_we_done_yet) return 1 return 0</code> | |
Lol, check my hub, think i'm in the same situation.
Though, my personal opinion is that if you write a decent project idea down before you start and if you use variables with logical names then why would i comment it? First of all if i wite a decent projec idea down i wont have to add stuff later on. And if i use logical var names then reading trough my proc would take just as long as when you add comment to it because after reading how the proc sould work you alwasy have to look how it actually works otherwise you cant implent anything. Personally i dont comment much, mostly because most procs are so small its not needed, though i had a project (my one and only damo :P) where i had a fairly huge proc and i didnt know anymore what i coded the day before and then decided i had to add comment, though would like to prevent this from happening in my next possible project. | |
Slipknight wrote:
My TAFE IT lecturer once told me "for every one line of code, I like to see three lines of commenting". That's just ... insane. Really insane. =P That much commenting and the code becomes completely unreadable. Which entirely defeats the purpose of commenting in the first place! I like to put comments at the beginning of procs and at the beginning of each block of code that does a specific mini-task. Like this: <code>mob/npc/proc/talk() //// Reads the NPC's next line of dialogue and displays it // Get the dialogue from the XML file (code here) // Parse the dialogue string for special commands (more code here) // Display the dialogue (etc.)</code> I also usually comment var definitions, especially if it's not clear from the name what they're for. | |
Slipknight wrote:
My TAFE IT lecturer once told me "for every one line of code, I like to see three lines of commenting". I don't believe that's necessary, but just enough commenting so that you get the general gist of what it's meant to do, understand? that's just plain evil, and that teacher should be tar'd-n-feather'd and hung from a train bridge for suggesting it (feel free to pass this along to him personally- we should not suffer idiots). so if i write: true = 1; I need to put 3 lines of comments in order to explain it? not only is that dense, but is a waste of development time. a 30-line program becomes 90 lines by his faulty suggestion. now then: commenting functions, procedures, and classes with three lines of comments *does* make sense, as it gives you the chance to describe what that block of code does and/or how to use it. maybe even a lengthy description of a line of code that has a very complicated algorithm in it. but three lines? make sure the rope he hangs from loops around the track. | |
The amount I comment depends on two things, how obvious what a segment of code does and if anyone else is working on the same project as me. In DM on my projects I do myself I rarely comment and only leave myself brief notes here and there if a piece of code isn't obvious. But when working in ASM I tend to litter my source code with comments since it's very easy to lose track of what your source does especialy for any sort of algorthim.
What is poor commenting practice is doing stuff like this. var/x = 1 // Initializing the x to 1 var/a = x * x //Setting a to x squared This is quite stupid since anyone who understands DM even the slightest wouldn't need to read the comment to figure it out. But if the variable label x was an abbreviation for something important that isn't obvious you should state in the definition with a comment what it's supposed to be. | |