Jump to content

  • Log In with Google      Sign In   
  • Create Account

We're offering banner ads on our site from just $5!

1. Details HERE. 2. GDNet+ Subscriptions HERE. 3. Ad upload HERE.


do you comment?


Old topic!
Guest, the last post of this topic is over 60 days old and at this point you may not reply in this topic. If you wish to continue this conversation start a new topic.

  • You cannot reply to this topic
210 replies to this topic

#1 Gaiiden   Senior Staff   -  Reputation: 5250

Like
Likes
Like

Posted 04 September 2000 - 08:00 PM

Hello!! For those just joining in after reading the article I wrote, prepare yourself. This is a long thread and I doubt you'll want to read it all. However, I urge you to try and skim through everything. We had a really great argument going on here with CloneMaker battling against the rest of the world against commenting code. Spaced elswhere throughout the thread are some really great comments, arguments, and suggestions. Just recently I added an email response I got from a reader with a great suggestion. It's on page 7, have a look. I started this thread with the intent of seeing how many others commented like me, and not only did it take off, I learned a lot! Hope you do too. Below is the post that started it all...
quote:
You know, after finishing and documenting a program I wrote for the company I work for, and having my buddy and coworker shake his head at the detail I put into it, I started to wonder: How well do you comment? Me, I learned the hard way. I've always had the habit of starting a project, dropping it and coming back to it a few days or weeks later (sometime after starting yet another doomed project - a habit I'm desperatly trying to break). However, when i got back to my old program, I'd open it up, take one look at a function and say to myself: "What the $#*! does THIS do?" So ever since I've gotten into the habit of commenting just about every single line of code. It's taken me a while, but I've finally settled on a method that doesn't clutter up the screen and mix up comment and code so much it becomes unreadable - a bad twist to a good thing. I even go so far as to point out what the parameters or arguments do in a function, as well as explain the nature of the function in detail. What this has led to is the ability to put a project aside, come back to it later and just read through the code and relearn all that I had done with it and start off right where i left off, a wonderful thing. So if any of you newbies haven't gotten into the habit of commenting, or you experienced people as well, do it. i don't care if you think you have a good memory, or that it takes too much time, or that it makes your .exe larger (not true, since all comments and white-space are taken out during compiling). The plain fact is that commenting HELPS whether you like it or not, and I can garuntee it'll get you on the good side of any game developer looking to hire you. (although when my computer science teacher tried to hug me for my wonderful commenting, I was a bit scared... don't worry, it was a woman) ============================== \\// live long and prosper; \||/ die short and rot. ==============================
============================== "Need more eeeenput...." - #5, Short Curcuit ============================== Edited by - Gaiiden on 10/31/00 3:10:25 PM

Sponsor:

#2 Ironblayde   Members   -  Reputation: 130

Like
Likes
Like

Posted 04 September 2000 - 10:56 PM

Sounds like me... I used to not do any commenting at all, but I got irritated when the code for one too many of my programs went from painfully obvious to painfully crpytic after only a month of not looking at it. Now, like you said, I comment all over the place, and have developed a ''style'' of sorts so that it doesn''t clutter up my code. I have fewer shouting matches with my computer this way.

-Ironblayde
 Aeon Software

#3 Gaiiden   Senior Staff   -  Reputation: 5250

Like
Likes
Like

Posted 05 September 2000 - 03:27 AM

exactamundo! My own monitor is now safer as as result of commenting, tho my mouse and keyboard still take abuse. I wonder if there''s anuyone out there who hates commenting for some arcane reason. Well? Anyone??

==============================
\\// live long and prosper; \||/ die short and rot.
==============================

#4 MadKeithV   Moderators   -  Reputation: 971

Like
Likes
Like

Posted 05 September 2000 - 03:32 AM

You do learn the hard way when doing lots of heavy coding.

On the MXMCLIV'th iteration of debugging my mesh subdivision code, suddenly everything goes blurry. What does this code do? Why did I call that index xi? What's this variable tempTriPtr32?

Since that happened ( about 24 times ), I've tried to comment WHILE I was programming, as opposed to my old style of "I'll do the comments when the code works". Comments are there for when the code DOESN'T work!
That was a very important paradigm shift for me - the comments are no longer there for someone else to figure out how beautiful my code is, it's there for me when I'm trying to find out what kinds of stupid mistakes I've made typing that stuff out.

Ps: my commenting style when sharing code with other people is like this:
    
/* [Insert short nametag here, [JT] in my own case] comment
* more comment
*
*/


That way, people know who wrote the message when looking at the code, so they know who to blame if it doesn't work right .

I also have a set of DevStudio macros that I use to layout my files( from Code on the Cob, right here on gamedev ), because it really helps when looking stuff up later.


Give me one more medicated peaceful moment.
~ (V)^|) |<é!t|-| ~
ERROR: Your beta-version of Life1.0 has expired. Please upgrade to the full version. All important social functions will be disabled from now on.

Edited by - MadKeithV on September 5, 2000 10:34:59 AM

#5 Krylar   Members   -  Reputation: 122

Like
Likes
Like

Posted 05 September 2000 - 04:34 AM

One thing that really bugs me is when I pay for a product that includes source code for customization, and it''s not commented.
I had to do a project recently that required code changes to a product purchased with source...took me 18 (literally) hours to do what should have taken 2 hours. Was VERY annoying and mushed my brain.

So, yes, I comment my code because some day someone else is going to have to modify it...and that somebody may be me!

-Krylar
Christian Coders Network

#6 justj   Members   -  Reputation: 122

Like
Likes
Like

Posted 05 September 2000 - 06:06 AM

At my job, I''m notorious for not commenting. I''ve never had a problem with my own code (IBM MVS Assembler), even after some years, but others are not too happy with it. I think the biggest reason is that I can think of code faster than I can type and I just hate to stop and comment.

Working in C++, though, I comment the hell out of everything, mostly because I don''t understand it that well myself and I sure can''t code faster than I can type. I don''t think C++ will ever lend itself as well to ''speed coding'' as assembler does.

"things are more like they are now than they ever have been"

#7 furby100   Members   -  Reputation: 102

Like
Likes
Like

Posted 05 September 2000 - 06:14 AM

When I write code, I do not seem to need to comment it very frequently. This is due to my good interpreter brain, my very good memory for code, and the fact that I use very descriptive funtion and variable names. I usually only get a comment every five lines.

------------------------------
#pragma twice


sharewaregames.20m.com


#8 Gaiiden   Senior Staff   -  Reputation: 5250

Like
Likes
Like

Posted 05 September 2000 - 08:34 AM

Just remember, Furby, that if you ever have to give your code to someone else for some reason (a partner perhaps) you should make sure he can understand it without your help. Commenting is not only for you, but for other people. I would hate to give a sheet of code to a friend and have him calling me every five minutes saying "What does this function do?"

I''d show you all my commenting style, but for two reasons: one, its too long an explanaition to bore you with, and two, it''s my style, and I can''t garuntee you''ll like it. The only rule I use when commenting is not to let it interfere with the readability of the code itself. Its good if you comment every line meticulously (like me) but if you do it to the point were the code and comments start to intermix and jumble, well, you''ve just defeated the purpose!!

==============================
\\// live long and prosper; \||/ die short and rot.
==============================

#9 Peon   Members   -  Reputation: 276

Like
Likes
Like

Posted 05 September 2000 - 05:00 PM

I''m busy doing cout and pointers and stuff (*yawn!*) and I still comment... everything. I comment variable intialization, every function... pretty much everything. Maybe that''s bad, I dunno. I just want to get in the good habit of commenting (even if it takes more time), cuz I know it''ll be good for me later (like brushing your teeth, hehe )

#10 Moe   Crossbones+   -  Reputation: 1248

Like
Likes
Like

Posted 05 September 2000 - 05:44 PM

I guess I am a little like furby100 except that I like to comment, at least every 5 lines (unless filling out something like a RECT structure). I also like to use descriptive variable/function names.



#11 MadKeithV   Moderators   -  Reputation: 971

Like
Likes
Like

Posted 05 September 2000 - 08:41 PM

Commenting every five lines in C++ ?
Wow, I tend to stick to one big comment per function and a few short comments where the code gets ugly. People reading it are programmers, and most of your code should be fairly self-explanatory.


Give me one more medicated peaceful moment.
~ (V)^|) |<é!t|-| ~
ERROR: Your beta-version of Life1.0 has expired. Please upgrade to the full version. All important social functions will be disabled from now on.

#12 alexmoura   Members   -  Reputation: 450

Like
Likes
Like

Posted 06 September 2000 - 12:22 AM

Sometimes when things get confusing I actually comment the code before i write it I just describe topic by topic what I''m planning to do in comments and then proceed to write the code for each topic.

I haven''t still absorved the habit of commenting thoroughly, though

You know, I never wanted to be a programmer...

Alexandre Moura

#13 Gaiiden   Senior Staff   -  Reputation: 5250

Like
Likes
Like

Posted 06 September 2000 - 01:14 AM

Hey alexmora, that''s a cool idea. Sometimes I like to write some psuedo-code first, comment it, then replace it with real code. And as for the only people reading it are programmers, not all the time. More often than not you''ll get stuck with a boss that likes to stay on top of things, and he may not be a programmer. I''ve had to show my boss a few code samples so the documenting helps a lot cause then he can understand it and, of course, it gets me some suck-up points

==============================
\\// live long and prosper; \||/ die short and rot.
==============================

#14 rockslave   Members   -  Reputation: 122

Like
Likes
Like

Posted 06 September 2000 - 01:54 AM

Everyone''s gotta comment! It''s good for understanding the algorithm, specially when your programming in groups. But the best is to make a "pseudo-code" like you said, or better, write the picture of the program working. But you don''t need to comment that little test programs, though.

Thanks, Arthur(rockslave)

#15 isrking   Members   -  Reputation: 122

Like
Likes
Like

Posted 06 September 2000 - 02:11 AM

Commenting is great and I try to comment functions and complicated sections of code as much as possible. I have had the misfortune of reading several programs where the commenting style was chaotic. If you don''t organize you comments well it can make reading and understanding the code even more difficult. I find that a good practise to have is using variable and function names which are meaningful. By doing this you can avoid having to write too many comments. I don''t know about anyone else, but I hate reading code where someone uses a variable x all over the place and you sit there wondering what x is supposed to mean.



#16 Gaiiden   Senior Staff   -  Reputation: 5250

Like
Likes
Like

Posted 06 September 2000 - 03:44 AM

well, rockslave, I don''t comment the psuedo code as much as ther real code but I still do just to keep up the routine and to keep it from getting confusing, cause I make up my own functions and stuff.

==============================
\\// live long and prosper; \||/ die short and rot.
==============================

#17 felisandria   Members   -  Reputation: 739

Like
Likes
Like

Posted 06 September 2000 - 05:28 AM

Having been a firefighter on legacy code for a while, I find comments invaluable. Remember, someday even 5 years from now when you''re possibly long gone, someone will have to figure out what the heck you were thinking. Comments as simple as "sorry, this is a kluge" can even be helpful.

Personally, if something isn''t painfully obvious, I comment. If something is "tricky", then I put a long comment before I go into it explaining what it does, and how to expand it (for instance, right now I have about 20 buttons on a dialog going through a single function which decides who sent it a message and processes it. If anyone ever tries to add another control to it, they''re going to be more than a little confused, so I will put a comment block in in a minute here telling them how to do new buttons right.)

A few things:
Whitespace is gooooooood. It improves readability. Use it, darnit.

Variable names that have some bearing on what they refer to are gooooood. "j" means nothing to me, unless it''s obvious it''s for a "for" loop right there. We have splendid machines with plenty of room for the extra letters for variable names. Use that space.

If I find out any of you are doing incrementals in an "if" statement or the like, I will hurt you unless you have a darn good reason. That''s so hard to find when you''re trying to do a badly needed and time-crunched fix.
ex: if (a > i++ && i < b++ && b++ < c)

Too many comments is better than too few.

-fel

#18 braves   Members   -  Reputation: 122

Like
Likes
Like

Posted 06 September 2000 - 05:45 AM

Do you know what commenting I really hate?

x = 0 //sets x to zero

while(x < 5) //beginning of loop
{
x++;//Increments x by 1
}//end of loop

I can't stand this commenting....
Braves



Edited by - braves on September 6, 2000 12:47:08 PM

#19 Thrump   Members   -  Reputation: 169

Like
Likes
Like

Posted 06 September 2000 - 08:22 AM

Never comment.


It lessens your ability to read uncommented code...



#20 Gorky   Members   -  Reputation: 122

Like
Likes
Like

Posted 06 September 2000 - 01:23 PM

Have fun with the comments if you can.
Some of my co-workers don''t appreciate humour in comments, but some do. I think it helps lighten the moode of the viewer.

No: delete(b_ticketingMod) // Delete the ticketing mod item

Yes: delete(b_ticketingMod) // Toast the puppy!

Of course, only do this on lines that are fairly obvious.





Old topic!
Guest, the last post of this topic is over 60 days old and at this point you may not reply in this topic. If you wish to continue this conversation start a new topic.



PARTNERS