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

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

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.
==============================

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

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

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"

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

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.
==============================

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 )

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.