A good programmer should have BOTH well written, easy to understand code, as well as comments when needed.

If I write out a highly complex texture alteration algorithm, no matter how nicely done it may be, I STILL have to put comments in there, because it is a complex part of code, which requires understanding as to WHY I copy this pixel here and that pixel there.

I type relatively fast (never really timed myself). I can think any thought out in English and type it out just as fast as I can think that. I could write 500 lines of comments in a few minutes without ever really stopping to think what I was writing (provided I do know what I am writing about to begin with).

Could I do this with a program?

I doubt it.

Also, keep in mind that comments are not case/spelling sensitive (I could type "theis functshun calculates the vertex normal of the given vertex", and would understand that just as well as if I had written it out properly, whereas I could not type
int iMaximumValue = 0;
iMaxvalue = iMaximumValue + 1;.)

Comments hardly take anywhere near the time to write out as your code does.

All you really need for comments anyway is something for each function, and then stuff for the complicated bits.

//-------------------------------------// HRESULT DoSomeThing()// This function does some stuff//-------------------------------------HRESULT DoSomeThing(PARAMETERS param){<...>if(FAILED(hr = DoSomething(somevalue)))return hr; // recurse through if nothing goes wrong.}

Is that so complicated?

Ok calm down everyone nuff is enough
ok you are all watching this from the commercial view and what you say about commenting is right that way but not from point of view from a guy who loves to code and don''t does it to earn money besides maintenance here isn''t an arguement u don''t have to do that cuz things are released only when they are bug free
AND i am not the guy who started to this thread

ImmaGNUman,

The problem is that what is excessive is a relative term. Someone that doesn''t know C/C++ would need the comment you used as an example. You can argue they have no business in your program, but what if you are mainly a VB shop with only C/C++ where it is needed for performance. All I am saying is that personally I don''t use comments. It isn''t hard to strip the comments out of a program so excessive or otherwise I don''t really care. I will strip it, figure out what changes are needed and where, then make the changes in the original program. I will also change existing comments if a change invalidated them and comment it however the original was commented. If they put comments on every line then I''ll put comments on every line. I will also add a history of revisions at the top and flag the start and end of any changes for that revision. It isn''t for my benefit though.

I''m not sure what anyone here means by translate to pseudo-code. If they mean do I think of r++ as increment r after using the value, then most certainly. I do admit that sometimes I think r plus plus, but it means the same thing to me and is mainly from the repetition of typing it. If they mean I can''t read a routine without translating it to pseudocode on paper they are wrong and you with them. If I write anything down it is the value of variables, but if possible I''m going to use a debugger instead so I don''t have to write them down. I do often reformat code so that it is readable. I''ve certainly seen plenty of unreadable code, but the solution to that problem is reformating it. Most code that is difficult to understand is either complex logic/math or poorly formated. I can''t really think of a case that it isn''t one of the two and you can fix one. If it is complex then comments is not going to make it simple to understand. The complexity is the difficulty, not the language.

My main point is that if I''m coding it for me then the comments are pointless. I don''t do it and as far as I''ve ever been able to tell I don''t suffer for it. My expertise is in performance tuning large databases in decision support systems so perhaps my views will change because this is a new area for me. When I first got out of college I shared many peoples views. I think it is a great aid for a beginning programmer. Eventually you learn the language you are using well enough that you don''t need the aid. It is just like a foreign language. Many people that I either went to school with or worked with were orginally from other countries. They start out translating into their native language to understand what is being said or what they are reading. When they speak they think of what they want to say in their native language and translate it. Eventually that process become automatic. The same happens with code if you are buried in it 60 to 80 hours a week. Saying it doesn''t is like saying you always have to remember to put one foot in front the other when walking. Yes you do have to put one foot in front of the other and to do so you technically have to think it, but hopefully you don''t stumble and fall because that cute blond just walked past you. You run into the wall instead

Daveb,

Please, pray tell, what is your worldly experience. Tell me of all your great and wondereous achievements. Then prove it :-P

Gladly.

I work for Volition. I shipped Freespace (Conflict:Freespace for those of you overseas ), was lead programmer and lead designer on Freespace 2, as well as Silent Threat, the expansion pack for Freespace. I was one of the two main PSX2 guys on Summoner, a PSX2 launch title which shipped several weeks ago.

Feel free to email me, its in my profile.

And I'll repeat it again - if you're saying you don't use comments, and even go as far as to remove comments from code before working on it, you've got to be nuts. I'd really like to know what software house _you_ work for which allows this kind of policy.

Edited by - daveb on November 5, 2000 3:31:41 AM

I disagree, daveb. I''ve been a professional programmer for over 10 years and I agree more with the 20 year guy than with your view.

Comments can be good, but too many people ignore the fact that BAD COMMENTING IS WORSE THAN NO COMMENTING AT ALL. And far too many people write BAD COMMENTS!

It is also true that the amount of commenting needed is inversely proportionate to the how well the code is written! Code that is written with good white spacing, a consistent style throughout (use whatever brace indent style you want, but don''t switch from function to function) and good variable names generally needs far less commenting than obfuscated, poorly written code.

I comment maybe 1 line out of 100-300 in my projects and it has never been a problem for any of the employers, contract clients or coworkers I work with because my code is clear and easy to read. I don''t write method/function names such as TrLList(),
I write them as TraverseLinkedList() (as a simple example).
Yes, this results in more typing, but you can clearly see how using one name would benefit from comments and using the other should be clear to any decent programmer. And using the longer name makes my code more clear in every spot that method is called from. The same applies to variable names. Don''t name everything a, b, i, j, k. Give variables appropriate names!!
You might have to type more (Intellisense saves you a lot of typing in this regard, at least when it comes to method names) but your code is clear with or without comments.

Of course, intelligent naming conventions are critically important. Conventions for module function names, class member names, globals, etc, etc.

But this can never be a substitute for comments. I"m not arguing against over-commenting. I don''t think over-commenting is an issue for any decent programmer.

But suppose you had a function like this :

int generate_combat_value(struct some_combat_struct *whee, float *val);

Now, lets suppose whee had 10 or 20 members in it. Generate combat value uses all of them (perhaps using some helper functions along the way) to generate this number. But its uncommented. So you''d have to guess :

- does it return the combat value or is that an error/success code? Is it 0 on fail, or < 0? Or nonzero?

- what exactly is the combat value? how is it generated? What is float *val? Is that where the return value comes from? Or is it an input array of numbers? Or a temporary?

- no "smart" naming convention in the world is going to be able to undo the need to comment the 20 struct members and complicated functionality of generate_combat_value().

A single line of comments would answer all these questions. I simply cannot see how you can produce release-quality code without them. How can you _possibly_ advocate writing code that causes others to _guess_ at how it works? That''s a surefire way to screw your whole project. For this reason alone, I cannot accept the fact that you''ve got the experience you say you do.

Not having comments in code significantly impacts code reusability and "fixability". When you write code you always assume someone else will have to modify it. Maybe you''re some super mega programming genius who is so good he has no need to do it. But I tend to doubt it. I''ve had the fortune to work with some of the smartest programmers in the world - none of them have ever subscribed to this theory.

quote:

---

Original post by gmcbay
Don''t name everything a, b, i, j, k. Give variables appropriate names!!

---

Boundy Laws of Naming

The wise programmer does not give two names to one thing nor attribute two things to one name.




Names are meaningful and specific, and their length is proportional to their scope. A loop variable used only once in a two-statement loop may be called "i", but a global variable that may be used anywhere in the program will have a long name that accurately describes its usage.-----D. Boundy

-http://www.robelle.com/smugbook/laws.html

(In case any copyright nazis want to know where I got this from.)

That says it better than I could have.

In msn12b speak: If you have a function/member/method that other code will call, give it a descriptive name. If not, make sure you can understand the name in its scope.

MSN

Daveb,

Perhaps the following example would get my point across to you: DDSURFACEDESC2. Perhaps you find this hard to believe but I don''t really care what comments are in the code for IDirectDraw7::CreateSurface. All I care about is how to use it and if you read my posts I said that before you worry about comments write the frigging documentation. Comments are not a substitute for it. Now if I have to actually look at the code there two reasons. Either it runs too slow or doesn''t work right. The comments don''t help me in either case. Do you really think the comments are going to say:

// The following line should have been iValue = ++iOther;iValue = iOther++;[/source]or[source]// I Should have initialize value outside loop and incrementedfor (iCurrRow = 0; i < iMaxRow; iCurrRow++) for (iCurrCol = 0; i < iMaxColumn; iCurrCol++) int *piBufferOffset = iCurrRow * iRowLen + iCurrCol;

If the code works fine all I care about is how to use it and then I want program documentation, not comments. Hypertext links so I can jump from the explaination of the function to the explaination of the structures it uses. If you fail to produce program doc then yes I am forced into the code. Comments are not going to be making me feel you are a professional programmer at that point. Using names such as Whee and Val is not going to make me feel that way either. If you did the same thing with the names in the structure I''m going to think you are a glutten for punishment by forcing yourself to work on such garbage. Even if you did good naming I''m going to question your choices if you calculate some_combat_struct.right - some_combat_struct.left instead of giving it a member function that returns width. All these little pain in the ass things is the problem, not the lack of comments. Good names alone won''t do it, you are right, but if you can explain it easily in a few comments then it isn''t that complicated. I know this is a difficult concept for you, but if you can express it simply in one language then it is a simple concept. Explain implicit surfaces to me in one sentence so that I understand it well enough that I can implement it. Ok, do it in ten. How about 100? With good naming practices all you are doing is replacing operators with verbs, possibly changing the nouns slightly and added a few, um, what are they called, adverbs and adjectives, that don''t really matter to the logic.

As for your specific questions. Return values are what is in the return statements. Where a constant is returned it is usually an error code. So if I saw else return(0) then it most likely returns zero on failure. If I saw instead return(COMBAT_VALUE_ERROR) then I wouldn''t really care what it returned because I would just check for that value. I know it is an integer and that is all I need to know about an error in that case. So using good names does make a differance there. It flags the code so you can easily see the error returns and a small step from that tells you what conditions lead to what error returns.

If I didn''t have any idea what the return value is then why would I be calling the function? Just for the hell of it? I don''t think so. Perhaps you do that, but I don''t. If it is an existing program that already calls it then it did something with the value returned. That gives me some idea what it is which implies a little about how it was calculated. If it is then used in an if statement determining if a hit was scored then the realm of how it might be calculated is reduced considerably. If the code is well written then you can easily pick out the major factors in the calculation. It isn''t just a glob of code, but rather a series of operations. You have to pass test a before b is checked, you have to pass test b before c is checked. Then I only have to understand a few lines at a time. Oh, they checked where the hit was, then the armour rating on that section or some such. If they increment Val then hopefully the input was an array, but the function won''t tell me that and the comments can''t either. That is under the control of the call to the function. They could pass a pointer to an integer for all the function knows. All the code or comments can tell you is what was suppose to be passed.

Finally with the examples of your naming conventions in this I would have to agree that all the comments in the world are most likely not going to make up for your poor choice in names. Oops, sorry, my mistake all the comments in the world won''t make up for the convoluted code. Oops, that wasn''t it, all the comments in the world won''t make up for the lack of object oriented design. Oops, that wasn''t it. What was your point?

Now as far as your experience. I will certainly agree that professional game development is professional programming, but it rather skews your view of the world. Generally you have relatively small, highly skilled staff. Standards are easily agreed upon and enforced. Communication is direct and easy as well as bearacracy being at a minimum, but that is because you are a small organization. You are lead programmer out of how many programmers? Five or ten? That is an acheivement. Congrats, but I was lead programmer, actually technical architect, out of fifty split between two countries if you count Canada as a country instead of a state :-P That was out of an I/S organization of 2,600. We always had 200 to 300 job openings that would go months unfilled. Over 100 of those had gone unfilled for over a year. The annual operating budget excluding labor was $10 million for my system. Our annual budget for all I/S excluding labor was $250 million a year.

That isn''t meant to impress you. There isn''t any reason for it to impress you because it has nothing to do with game development and when it comes to game development I''m a newbie. I''ll tell you I envy you because the environment you work in is a world apart from the one I was in. I would certainly like to be in a environment where I could not only trust that I won''t have a strong urge to cring when I look at the changes someone just completed, but to actually have to defer to their skill. My experience has been out of 2,600 we considered 700 to be technologist which means their core skill was actually using/prodcuing technology rather than systems analysis or project management. Out of those 700 we had perhaps 100 that were what you would really consider good. Not average, but actually good. Out of that we had perhaps 10 to 20 that were world class meaning they can hold their own with virtually any expert in their subject area. That is the norm in extremely large organizations. I fell in that last group. When it comes to milking performance out of a multi-terabyte database it is a rare individual that is my equal no matter their experience. That skill comes from being able to understand what the entire system is doing, where the work went and make a few surgical changes that knock huge chunks of work out of the system while doing the same thing. That means going wherever the code is, with or without documentation, in whatever language it is in, with or without comments, good comments, bad comments, excessive comments, well structured code, f''ed up code, good variable names, bad it doesn''t matter. Now you can argue you are my equal when it comes to sorting through mountains of f''ed up code to find what you are looking for and I won''t argue with you. When you start arguing I can''t do it that is a differant story. That is as far as I''m concerned nothing but a personal attack. Believe whatever you want because I don''t have anything to prove to you. You choose to not believe anything outside the realm of your own personal experiences and that is your problem and not mine.

Strip the comments from the Linux kernel, and tell me what it does line by line. If you cant do this, then you better be commenting your code.

-----------------------------

A wise man once said "A person with half a clue is more dangerous than a person with or without one."

The Micro$haft BSOD T-Shirt

That would be pretty easy, but would take a long time, there are a lot of lines Line by line wouldn''t be difficult, i.e. it adds this variable to that. Explaining why is the difficult part but the difficulty is the complexity. Now to mirror that back, implement the Linux kernal from just the comments