• ### Announcements

#### Archived

This topic is now archived and is closed to further replies.

# do you comment?

## 210 posts in this topic

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
0

##### Share on other sites
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
0

##### Share on other sites
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.
==============================
0

##### Share on other sites
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
0

##### Share on other sites
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
0

##### Share on other sites
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"
0

##### Share on other sites
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
0

##### Share on other sites
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.
==============================
0

##### Share on other sites
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 )
0

##### Share on other sites
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.

0

##### Share on other sites
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.
0

##### Share on other sites
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
0

##### Share on other sites
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.
==============================
0

##### Share on other sites
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)
0

##### Share on other sites
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.

0

##### Share on other sites
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.
==============================
0

##### Share on other sites
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
0

##### Share on other sites
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
0

Never comment.

0

##### Share on other sites
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.
0

##### Share on other sites
quote:
Original post by Gorky

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.

I don''t do it often but sometimes the temptation is just too strong . Last time it happend the day after I saw "The Matrix":

// - We will need a search running.
// - It has already begun.
pfoo->RunSearch();
0

##### Share on other sites
I know what you mean braves. Like where people go:
#include  // include windows header file#include  // include standard i/o header file

or like you said:
if (x==0) // test if x is equal to zero{ x=5; // make x equal to 5} // end the "if x is equal to zero" statement

A little exaggeration but you get the idea. In game programming, I pretty much only comment the algorithms and functions that may be confusing. I don''t comment Initialization and stuff. In regular programming, I find it helpful to comment the things felisandria was talking about.

------------------------------------"We are the music makers, and the dreamers of the dreams."
- Willy Wonka
0

##### Share on other sites
Comments are mandatory. But they need to be smart comments. I prefer to comment what a block of code does (in english), and if need be why it works that way. Let the code speak for itself, unless you''re like some of the guys I work with who use 90% magic numbers, no comments, and no design documents. Its a nightmare!

But commenting is something that any good company requires, and any interviewer should ask about and look for in sample code. You have to get in the habit. I think they''re very helpful even for single person projects, but any good company will trade off some development time for well documented code. It saves time in the end, without a doubt.

Rock
0

##### Share on other sites
I think commenting is a waste of time. You should learn
to read code as you would English text. Many times code
is modified and the coders are too busy or lazy to update the comments.
I remember one lecturer at my old university would strip the comments out of code and tell us to figure out what it did.
The lecturers name was Rob Pike.
0

##### Share on other sites
quote:
I think commenting is a waste of time. You should learn
to read code as you would English text

I''m sorry Davaris, but that I completely disagree (with the
first sentence anyway)...

I CAN read most code that I see and understand it straight away.
I CAN spot many mistakes in peoples code w/o compiling.
Every bit of syntax that I have learned I have taken time to
master.

But i still comment.

Just because you can read code and interpret it, doesn''t mean
that comments are useless. If I''m writing a large program I
would rather see comments like "This bit eats all the RAM"
every 10 or so lines then no comments at all.

Comments are an aid that can half the amount of time needed to
understand code.

why refuse yourself the benefits they have to offer?

----------
Erick: i think that all this talking and such is paining my head to astounding annoyance
Disco Love For Everyone
0