Pretty easy? You can explain to me every single line of the Linux kernel and why they did what they did without comments and it would be pretty easy? Yeah, and I have monkeys coming out of my butt...

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

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

You didn''t say anything about why they did it. If you get the monkeys out of your ass and read my post instead of just replying you would see that I pointed that out to you. You just said explain line by line what it is doing. You said nothing about why it was doing it.

LilBudyWizer - If you were to understand the linux kernal, would you find comments useful or not?


Mike

Everyone seems to be missing a big chunk of the picture here... Maybe you don''t need comments - if the program documentation is good - to understand what it does and how to use it... but, an example...

You''re working on a small program, say seven source files named "Graphics", "Levels", "Main", etc. Your "Graphics" source file is a few hundred lines long, with around 30 functions, that are pretty much as modularized as is reasonable to make them. It handles loading graphics from a file, drawing them, and the main render loop. You know you have a bug in the file loader, but where is it? It''s much easier to skim the file for a nice, large header-like comment (which sticks out big-time) than to read each function name trying to find a certain function. These take very little time to make, and almost never change, even if the code is edited by other people.

Or were you telling me this "documentation" should maintain an exact listing of the code line of everything it documents?



Secondly: I don''t know about anyone else, but if I''m trying to debug a program, I want to be able to read WHY it''s doing whatever (and if I''m understanding properly, this is what that "documentation" would tell you, but if I''m styaring at the code anyway, I don''t want to keep glancing between my screen and some book, I want to be able to read the comments right beside the code.

--Tr][aD--

Bud - the examples I gave were just that - examples. I was hoping you'd fill in the blanks and understand what I was trying to say. Even if you had a well-named 20 member struct, what would you give the function for a name?

int generate_a_combat_value_by_taking_members_four_five_and_six_dividing_by_the_number_of_oh_wait_this_is_retarded();

Congrats on zinging me by "assuming" I write that kind of code though! Score : you!

Document until you're blue in the face - super international programmer you may be, but I can't think of a single company that would give you a job if you went in and said "oh yes, comments are not necessary".

A friend of mine used to work at a phone company where they maintained a 50 million line telephone switch codebase. There were people there who spent their entire lives maintaining that piece of code. You're telling me you expect a new guy to read the documentation on 50 million lines of code and be able to go in and fix uncommented code on a system which runs hundreds of millions of phone lines? No.

But perhaps there's a blurring here between what you're calling "documentation" and what I'm calling "comments". Certainly, textual descriptions at the top of a module fall into both categories and can go along way towards revealing the philosophy behind the module. However, I _guarantee_ you I can write you a math-intensive function (for example) that fits perfectly into a well documented module, and it would take you a day to understand what was wrong with the function, _unless_ I put comments in the code. I'm sure your managers would love to see productivity soar like that.

Finally, you need to realize that when you're on this board, you're dealing with lots of _beginners_. Its all too easy to give them the wrong ideas. By going in and saying "comments aren't necessary" you're dooming the ones who take it to heart and then get into the habit of writing unmaintainable code. This is similar to the standard "USE C++ IT IS THE ONLY WAY TO DO THINGS" argument. You're just hurting those trying to get started.

(after a brief cooling down period)

I will certainly admit that software engineering, as practiced by the game development industry is far from perfect. There's no doubt we tend to shoot from the hip in terms of the process of programming. Of course there's no way we run a ship nearly as tight as your average consulting firm or large software house. Scale does matter. However, I still maintain that generalizing and saying "comments are unneccessary" and that you'd be just as well off by looking at the code and effectively guessing at what it does, is bogus. I would certainly hope large software houses don't want programmers guessing what individual functions and/or lines of code are doing. If your documentation is so completely thorough that it explains everything, well, then you've just got comments in a less useful place. Documentation != comments.

Edited by - daveb on November 5, 2000 11:33:16 PM

Ok, I''ve wasted to much time with this. I give up. I''m going to dutifully read every comment thrust before my weary little eyes and comment my programs so any newbie can understand them even if no one but me will ever see it. And if anyone asks me how to be a better programmer I will tell them as sincerely as I am able that they should write better comments. I realize now how foolish I was to think it was best to write better code.

Oh, I can''t give up that easily so here is a sample of my code...

[source]
#include "stdio.h"
#define e 3
#define g (e/e)
#define h ((g+e)/2)
#define f (e-g-h)
#define j (e*e-g)
#define k (j-h)
#define l(x) tab2[x]/h
#define m(n,a) ((n&(a))==(a))

long tab1[]={ 989L,5L,26L,0L,88319L,123L,0L,9367L };
int tab2[]={ 4,6,10,14,22,26,34,38,46,58,62,74,82,86 };

main(m1,s) char *s; {
int a,b,c,d,o[k],n=(int)s;
if(m1==1){ char b[2*j+f-g]; main(l(h+e)+h+e,b); printf(b); }
else switch(m1-=h){
case f:
a=(b=(c=(d=g)< return(m(n,a|c)|m(n,b)|m(n,a|d)|m(n,c|d));
case h:
for(a=f;a case g:
if(n if(n else{c=''\r''-''\b'';n-=j-g;o[f]=o[g]=g;}
if((b=n)>=e)for(b=g<=o[b-h]+o[b-g]+c;
return(o[b-g]%n+k-h);
default:
if(m1-=e) main(m1-g+e+h,s+g); else *(s+g)=f;
for(*s=a=f;a *s=(*s< }
}
[\source]

Now do you really need comments to explain to you what this simple program does? '' Target=_Blank>Link

Hehe, perhaps if I''m too old and befuddled to get the right slash I need a bit more than just comments. Just to give credit where credit is due and all that is really one of the winners of the Obfuscated C Code contest and is Hello World. I was just surprised you guys used the Linux kernel as an example. Now I don''t really think comments would help this program. Perhaps it would make it easier to change it to display "Hello World!", but I have my doubts.

Actually, in this case yes. This is exactly the time comments would be great. Pathologically nutty syntax notwithstanding, I'd rather just see

// this does X

than sit there and work things out bit by bit.

Now, if you _really_ write code like this (and I don't believe you do), you'd need to have your head examined.

If you _still_ really really _really_ don't think comments are necessary, I invite you to try PSX2 programming using all the wonderful Sony sample code with comments in Kanji , before they were translated You'd like it - you have to interpret everything by guessing what the engineers were thinking. Whee!. I'll see you in 15 years when you finally figure out the bit patterns of all 32+ GS registers through sheer inference.

Edited by - daveb on November 6, 2000 1:47:49 AM

I think I see your point. If the only documentation you have is in the comments in the code would I read them? Oh yes. If I''m calling some function in a dll that takes a parameter that is bit flags, there are no defines and the only documentation for what values are valid is in the comments then I''m going to read the comments. If the only explaination for the sequence functions have to be called in is comments in the header am I going to read it? Certainly I am. My only other choice is making wild guesses, trying every possible combination and permutation or disassembling it. I don''t consider those to be comments though. It is documentation buried in the code.

My point is not that comments are not important. If your coworkers want comments then that alone makes it important if nothing else does. My point is more that if you want to rightfully claim to be a professional programmer you need to do a bit more than just throw comments in a program no matter how skillfully they are written. I don''t feel it is the most important thing. First and foremost is the code. You screw that up and it doesn''t matter what else you do right. Next on my list is documentation for the program just like what comes with the DirectX SDK. Perhaps you never use help files and always look at the source instead, but personally I don''t have access to the source for DirectX and even if I did I would still look at the help file first. If the code works and I have that documentation then I could care less if Microsoft put a single comment in the headers, much less the source. I''m not going to read the line comments in the header files on the structures when all of that is in the help file and much better explained. A truely professional programmer will produce a programming and referance guide for their program. Perhaps it won''t be at that level of skill, but Microsoft is using professional technical writers, not programmers to produce those.

Code first, documentation second and comments third is my priorities. Professional is not a matter of how much money you make or how big a market share you have. It is the manner in which you perform your job. It sounds like what Sony did was highly unprofessional. You may be forced to suffer through their short comings, but that doesn''t mean they are professional. It just means they have a big market share, you need the money and they can get by with behaving in an unprofessional manner. Might makes right is not a new concept nor is it correct.