quote:
As for the whole "rewrite the module" argument - that''s completely stupid. What if the module is 15,000 lines of code and you have 2 days to fix a series of bugs. No way.
If you modularized correctly, your modules are divided into modules. There are no 1500 line long individual functions.
quote:
a.) You think that you''re so good you have no need to comment. When you get into the professional world you''re going to find that pretty much everyone is as smart or smarter than you. And they comment. You lose.
Where did I imply that I thought I was too good to comment? I simply stated that it was unnecessary.
quote:
b.) You think there''s no need to comment stuff because you can always re-write it. Real world time constraints make this a complete fallacy.
If there are major errors in a module, you''ll rewrite it anyway. If there are small ones, you can catch them without comments.
quote:
This is ludicrous, and you''re making yourself sound very dumb. In the "real" world, if you''re checking in code that doesn''t even compile because it has syntax errors you''d be fired in a week. The _vast_ majority of bugs in code are no syntax errors.
You''re saying typos are less common than large logical algorithmical errors?
quote:
Proper commenting allows another competent programmer to go in and fix someone else''s code. If you''re 3 days away from a drop-dead ship date, you can''t just go in and re-write major portions of code. And if you have to fix some serious bugs in a major module with no commenting, you may as well be doing surgery with a chainsaw. There''s a super-high chance that all you''ll do is introduce more bugs and further screw your release.
Like I said, if it is modularized correctly, then you can rewrite small modules that have major errors in them.
quote:
Let''s see, most code I work with has one line of comments per ten lines of code, and mabye one per three if it is extremly complex. I would like to know how you came to the conclusion that this happens ''often''.
Of course I put more weight into good variable/function names, but many times that alone is not sufficient and the code needs more.
If you comment this little, you still would need whoever is reading your code to decipher the code often. Most of the time if you do this, the person can either understand that one isolated relatively complex line, or find it out for himself because it is isolated.
quote:
You would be hard pressed to find many here that agree that the nuumber of charecters in comments is greater than thta of code. And if this happens, you may be over commenting. Of course if people write comments like ''want to right in a certian loop'', the reader will get confused.
The ratio of commented to non-commented lines is already being discussed in the previous point. But do you agree that in a single commented line the comments take up more characters than the code?
quote:
Are you on drugs? Exactly what part of what I said do you disagree with? I rarely get syntaxical errors, and generally finding bugs takes incredibly longer than writting the original code. Most large products go through multiple month long debugging processes, where new features are not added. I wonder why they don''t go through month long syntaxical fixing periods?
You''re saying you rarely make typos? Your paragraph prior to my quote had two typos. Out of about 50 characters or so. Surely you can see that you''re going to make typos in code and you''re going to get a fairly decent amount of syntaxical errors. True they don''t take long but most errors are ones like that.
If you modularize correctly, you can debug each separate function at a time. Making the debugging state not that long. The reason debugging states are long is because of general design errors. These can''t be fixed by comments.
quote:
It''s pretty obvious you have no real world experiance. When you get some, come back and we can discuss this further.
I consider your skeptancy on my years of experience in this market an insult. I haven''t personally insulted you, so please, have a professional attitude toward this thread.
quote:
Um, an *objective* view is not what you presented here. An objective view is when you argue for both sides. Your view is strictly subjective.
I did examine both sides. This is irrelevant though.
quote:
Also, you only argued that co-workers should know and it wont help yourself. However, no one reads code as good as English, besides the claims. Its impossible, because I can read badly formatted and to a certain extent misspelled English, but I severly doubt anyone can do the same with code. Pick any random .c file at www.ioccc.org and if you can read it like English, you deserve a quick slap in the face, for lying.
True, but in reality, comments are not english(obviously they are in literal terms, but you know what I mean) because when you read a comment, you formulate pseudocode for this. Then from this pseudocode you examine the code itself and determine its final meaning. This is the same length of time if you read code. You try to picture it the code in more increasing coherent general forms of pseudocode until you understand exactly what it means.
quote:
then you are right, comments are useless. But, as I said, comments are not there to state the obvious. They are there because of so many possible pecualuralities in any given peice of code, it becomes hard to maintain.
If there is one isolated complex line, then you can figure it out because it doesn''t pertain as much to the previous code, or the previous code is obvious enough that you can fit it in the scheme. If it is integrated into the code enough that it is dependant on the rest of the code, you need to comment that code also.
quote:
Heh. I''d wager this guy doesn''t have 20 years of experience. In fact, my rough estimate would be about, oh, zero.
Do not personally insult me. Let''s have a professional attitude in this thread, ok? I have in fact more than 20 years of experience.
quote:
Any supposedly "experienced" programmer who is arguing against the value of comments in his code is equivalent to a experienced soldier who is arguing against the value of bullets in his gun.
Your analogy is wrong. The bullets would symbolize code. Comments would symbolize the detailed instruction manual on how to load and utilize the bullets. The professional soldier doesn''t need to know this.
quote:
Eh, this argumnent is inane. If you''re an "undecided" programmer reading this, take it to heart - you''ll never make it as a professional programmer if you don''t believe in comments.
I would prefer if you would stop generalizing so much.
quote:
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.
The question "why" would refer to the general outline of the program. Obviously the pixel is important to the rest of what you put on to the screen, not just the individual pixel. It would be impossible to write comments that integrate each small part like this. Separate documentation is more efficient for this.
quote:
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).
So you write 500 lines of comments straight? No! Before you write a commented line of code, you formulate what you are going to do. The formulating involves both the englishized general pseudocode and the code itself in the same amount of time. You type out the line itself without really thinking about it, hence the comments get typed a little slower because of more characters.
quote:
//-------------------------------------// HRESULT DoSomeThing()// This function does some stuff//-------------------------------------HRESULT DoSomeThing(PARAMETERS param){<...>if(FAILED(hr = DoSomething(somevalue)))return hr; // recurse through if nothing goes wrong.}
First of all, the format of that comment up top takes time. You don''t need to know the return value because it already says. And you should be able to have descriptive enough function names for someone to figure out what they do.
The recurse through part is obvious and does not need to be commented. Most people can understand if statements and can point out recursion quickly.
quote:
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.
I must say you''re quite arrogant. George W. won the election, he has(or will have) experience, does that mean his policies are right?
quote:
- does it return the combat value or is that an error/success code? Is it 0 on fail, or < 0? Or nonzero?
You can figure that out from the code.
quote:
- 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?
The combat value is also easily figured out from the code. And val is a bad variable name. That''s the only reason we can''t tell what it is.
quote:
- 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().
Not if each member has a descriptive name.
quote:
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.
They don''t need to guess. If you modularize correctly, each separate small algorithm is divided well enough that you can figure out what it does.
quote:
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.
The function names should be descriptive enough to aid you enough as comments do in your query.
quote:
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.
If you understand the general purpose of each section of code, then you don''t need comments to examine each section and figure out what it does.
quote:
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!
The documentation is sufficient to understand what each function does related to the general larger module.
quote:
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.
The documentation should be sufficiently divided that you can find what a function does.
quote:
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.
First of all, why would you care if we understand it?
Second of all, if it is math intensive, you are going to spend the same amount of time understand the code alone compared to the comments and the code. Code you turn into more general and general pseudocode. Comments you turn into more specific and specific pseudocode until you get to the actual code.
quote:
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.
Individual lines should be comprehendible enough to mix with the general surrounding lines, figuring out in general what it does in pseudocode. The documentation generalizes it saying why everything does what it does.
So many posts, this is tiring...
quote:
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.
Like I said before, most short functions are easily comprehendible, and even if they''re not, comments won''t help.
quote:
If your coworkers want comments then that alone makes it important if nothing else does.
Why?
quote:
For the second case, it''s better to write comments as you are writing GOOD code. Not the obvious comments, but the ones that will help you write good documentation when you''ve finished that code.
Why?
quote:
If you are just going to call other people''s code and use it as a black box, then of course documentation outweighs comments. If you actually try to maintain their code and figure how it works, then comments would outweigh documentation.
If it''s modularized correctly, you can figure out what each small part does as easily as with comments.
quote:
The1Blade, how many companies have you worked for where this was true? I have yet to work for a boss like this. And I DID work for a boss like this, I would look for another job because if he/she doesn''t care about his/her employees then you are in trouble.
In general, more bosses would not prefer getting complaints about the teamwork in the group. Not because of the validity of the claim, but because loss of teamwork will mean loss of production for a while. They get angry at the first person that informs him of such a situation, its natural.
quote:
What most of you are forgetting is that commenting should explain the code''s intent, and sometimes why, not summarize the code. Have you people ever worked for a company who has a huge application they want you to make an addition to, which you''ve never even looked at? If you think comments aren''t extremely helpful at that point then you''re crazy. I mean, you can look at a line of code and understand it, but you don''t know what the application as a whole is doing. Anyone can look at a line and say, "Yep, they are shifting the bits in this integer 3 to the left, but that doesn''t tell them what that section of code is supposed to do. I mean, what if this section of code has a bug in it? How are you supposed to know what the code was SUPPOSED to do without comments are an intimate knowledge of the program?
First of all, the comments themselves could be saying goals that you don''t really want in this line of code, so you can''t always base whether a line is good or not because of the intentions expressed in the comments.
2nd of all, the general role of a large module is better explained in documentation.
3rd of all, if you understand the previous lines, you''ll understand the result of a certain operation. From the code in the future you can find that the operation is not doing something properly.
quote:
That is one thing I agree with Daveb about. Commenting is a good practice. That I can get by without it doesn''t mean it shouldn''t be done. That you can get by without program documentation doesn''t mean you shouldn''t be doing it. If you have done it plenty of times before and it would only be for your own benefit then certainly there isn''t much point to it if you are not going to use it. If you have never done it then there is a benefit just as there is for a beginning programmer to comment. Not that beginning programmers are the only ones that benefit from comments, but rather they are pretty much the only ones that benefit from the process of commenting. It helps them reason out what they are doing to explain it in english. Program documentation does the same thing at a higher level. Working at a systems level means thinking of the program in the abstract. If you want to do something like STL, MFC, OWL or VCL then it is essential that you not bog down in the details. If you want to write something like Windows or DirectX it is also essential.
You haven''t explained why you should comment if you can get by without it.
quote:
As for the whole "rewrite the module" argument - that''s completely stupid. What if the module is 15,000 lines of code and you have 2 days to fix a series of bugs. No way.
If you modularized correctly, your modules are divided into modules. There are no 1500 line long individual functions.
quote:
a.) You think that you''re so good you have no need to comment. When you get into the professional world you''re going to find that pretty much everyone is as smart or smarter than you. And they comment. You lose.
Where did I imply that I thought I was too good to comment? I simply stated that it was unnecessary.
quote:
b.) You think there''s no need to comment stuff because you can always re-write it. Real world time constraints make this a complete fallacy.
If there are major errors in a module, you''ll rewrite it anyway. If there are small ones, you can catch them without comments.
quote:
This is ludicrous, and you''re making yourself sound very dumb. In the "real" world, if you''re checking in code that doesn''t even compile because it has syntax errors you''d be fired in a week. The _vast_ majority of bugs in code are no syntax errors.
You''re saying typos are less common than large logical algorithmical errors?
quote:
Proper commenting allows another competent programmer to go in and fix someone else''s code. If you''re 3 days away from a drop-dead ship date, you can''t just go in and re-write major portions of code. And if you have to fix some serious bugs in a major module with no commenting, you may as well be doing surgery with a chainsaw. There''s a super-high chance that all you''ll do is introduce more bugs and further screw your release.
Like I said, if it is modularized correctly, then you can rewrite small modules that have major errors in them.
quote:
Let''s see, most code I work with has one line of comments per ten lines of code, and mabye one per three if it is extremly complex. I would like to know how you came to the conclusion that this happens ''often''.
Of course I put more weight into good variable/function names, but many times that alone is not sufficient and the code needs more.
If you comment this little, you still would need whoever is reading your code to decipher the code often. Most of the time if you do this, the person can either understand that one isolated relatively complex line, or find it out for himself because it is isolated.
quote:
You would be hard pressed to find many here that agree that the nuumber of charecters in comments is greater than thta of code. And if this happens, you may be over commenting. Of course if people write comments like ''want to right in a certian loop'', the reader will get confused.
The ratio of commented to non-commented lines is already being discussed in the previous point. But do you agree that in a single commented line the comments take up more characters than the code?
quote:
Are you on drugs? Exactly what part of what I said do you disagree with? I rarely get syntaxical errors, and generally finding bugs takes incredibly longer than writting the original code. Most large products go through multiple month long debugging processes, where new features are not added. I wonder why they don''t go through month long syntaxical fixing periods?
You''re saying you rarely make typos? Your paragraph prior to my quote had two typos. Out of about 50 characters or so. Surely you can see that you''re going to make typos in code and you''re going to get a fairly decent amount of syntaxical errors. True they don''t take long but most errors are ones like that.
If you modularize correctly, you can debug each separate function at a time. Making the debugging state not that long. The reason debugging states are long is because of general design errors. These can''t be fixed by comments.
quote:
It''s pretty obvious you have no real world experiance. When you get some, come back and we can discuss this further.
I consider your skeptancy on my years of experience in this market an insult. I haven''t personally insulted you, so please, have a professional attitude toward this thread.
quote:
Um, an *objective* view is not what you presented here. An objective view is when you argue for both sides. Your view is strictly subjective.
I did examine both sides. This is irrelevant though.
quote:
Also, you only argued that co-workers should know and it wont help yourself. However, no one reads code as good as English, besides the claims. Its impossible, because I can read badly formatted and to a certain extent misspelled English, but I severly doubt anyone can do the same with code. Pick any random .c file at www.ioccc.org and if you can read it like English, you deserve a quick slap in the face, for lying.
True, but in reality, comments are not english(obviously they are in literal terms, but you know what I mean) because when you read a comment, you formulate pseudocode for this. Then from this pseudocode you examine the code itself and determine its final meaning. This is the same length of time if you read code. You try to picture it the code in more increasing coherent general forms of pseudocode until you understand exactly what it means.
quote:
then you are right, comments are useless. But, as I said, comments are not there to state the obvious. They are there because of so many possible pecualuralities in any given peice of code, it becomes hard to maintain.
If there is one isolated complex line, then you can figure it out because it doesn''t pertain as much to the previous code, or the previous code is obvious enough that you can fit it in the scheme. If it is integrated into the code enough that it is dependant on the rest of the code, you need to comment that code also.
quote:
Heh. I''d wager this guy doesn''t have 20 years of experience. In fact, my rough estimate would be about, oh, zero.
Do not personally insult me. Let''s have a professional attitude in this thread, ok? I have in fact more than 20 years of experience.
quote:
Any supposedly "experienced" programmer who is arguing against the value of comments in his code is equivalent to a experienced soldier who is arguing against the value of bullets in his gun.
Your analogy is wrong. The bullets would symbolize code. Comments would symbolize the detailed instruction manual on how to load and utilize the bullets. The professional soldier doesn''t need to know this.
quote:
Eh, this argumnent is inane. If you''re an "undecided" programmer reading this, take it to heart - you''ll never make it as a professional programmer if you don''t believe in comments.
I would prefer if you would stop generalizing so much.
quote:
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.
The question "why" would refer to the general outline of the program. Obviously the pixel is important to the rest of what you put on to the screen, not just the individual pixel. It would be impossible to write comments that integrate each small part like this. Separate documentation is more efficient for this.
quote:
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).
So you write 500 lines of comments straight? No! Before you write a commented line of code, you formulate what you are going to do. The formulating involves both the englishized general pseudocode and the code itself in the same amount of time. You type out the line itself without really thinking about it, hence the comments get typed a little slower because of more characters.
quote:
//-------------------------------------// HRESULT DoSomeThing()// This function does some stuff//-------------------------------------HRESULT DoSomeThing(PARAMETERS param){<...>if(FAILED(hr = DoSomething(somevalue)))return hr; // recurse through if nothing goes wrong.}
First of all, the format of that comment up top takes time. You don''t need to know the return value because it already says. And you should be able to have descriptive enough function names for someone to figure out what they do.
The recurse through part is obvious and does not need to be commented. Most people can understand if statements and can point out recursion quickly.
quote:
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.
I must say you''re quite arrogant. George W. won the election, he has(or will have) experience, does that mean his policies are right?
quote:
- does it return the combat value or is that an error/success code? Is it 0 on fail, or < 0? Or nonzero?
You can figure that out from the code.
quote:
- 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?
The combat value is also easily figured out from the code. And val is a bad variable name. That''s the only reason we can''t tell what it is.
quote:
- 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().
Not if each member has a descriptive name.
quote:
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.
They don''t need to guess. If you modularize correctly, each separate small algorithm is divided well enough that you can figure out what it does.
quote:
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.
The function names should be descriptive enough to aid you enough as comments do in your query.
quote:
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.
If you understand the general purpose of each section of code, then you don''t need comments to examine each section and figure out what it does.
quote:
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!
The documentation is sufficient to understand what each function does related to the general larger module.
quote:
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.
The documentation should be sufficiently divided that you can find what a function does.
quote:
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.
First of all, why would you care if we understand it?
Second of all, if it is math intensive, you are going to spend the same amount of time understand the code alone compared to the comments and the code. Code you turn into more general and general pseudocode. Comments you turn into more specific and specific pseudocode until you get to the actual code.
quote:
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.
Individual lines should be comprehendible enough to mix with the general surrounding lines, figuring out in general what it does in pseudocode. The documentation generalizes it saying why everything does what it does.
So many posts, this is tiring...
quote:
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.
Like I said before, most short functions are easily comprehendible, and even if they''re not, comments won''t help.
quote:
If your coworkers want comments then that alone makes it important if nothing else does.
Why?
quote:
For the second case, it''s better to write comments as you are writing GOOD code. Not the obvious comments, but the ones that will help you write good documentation when you''ve finished that code.
Why?
quote:
If you are just going to call other people''s code and use it as a black box, then of course documentation outweighs comments. If you actually try to maintain their code and figure how it works, then comments would outweigh documentation.
If it''s modularized correctly, you can figure out what each small part does as easily as with comments.
quote:
The1Blade, how many companies have you worked for where this was true? I have yet to work for a boss like this. And I DID work for a boss like this, I would look for another job because if he/she doesn''t care about his/her employees then you are in trouble.
In general, more bosses would not prefer getting complaints about the teamwork in the group. Not because of the validity of the claim, but because loss of teamwork will mean loss of production for a while. They get angry at the first person that informs him of such a situation, its natural.
quote:
What most of you are forgetting is that commenting should explain the code''s intent, and sometimes why, not summarize the code. Have you people ever worked for a company who has a huge application they want you to make an addition to, which you''ve never even looked at? If you think comments aren''t extremely helpful at that point then you''re crazy. I mean, you can look at a line of code and understand it, but you don''t know what the application as a whole is doing. Anyone can look at a line and say, "Yep, they are shifting the bits in this integer 3 to the left, but that doesn''t tell them what that section of code is supposed to do. I mean, what if this section of code has a bug in it? How are you supposed to know what the code was SUPPOSED to do without comments are an intimate knowledge of the program?
First of all, the comments themselves could be saying goals that you don''t really want in this line of code, so you can''t always base whether a line is good or not because of the intentions expressed in the comments.
2nd of all, the general role of a large module is better explained in documentation.
3rd of all, if you understand the previous lines, you''ll understand the result of a certain operation. From the code in the future you can find that the operation is not doing something properly.
quote:
That is one thing I agree with Daveb about. Commenting is a good practice. That I can get by without it doesn''t mean it shouldn''t be done. That you can get by without program documentation doesn''t mean you shouldn''t be doing it. If you have done it plenty of times before and it would only be for your own benefit then certainly there isn''t much point to it if you are not going to use it. If you have never done it then there is a benefit just as there is for a beginning programmer to comment. Not that beginning programmers are the only ones that benefit from comments, but rather they are pretty much the only ones that benefit from the process of commenting. It helps them reason out what they are doing to explain it in english. Program documentation does the same thing at a higher level. Working at a systems level means thinking of the program in the abstract. If you want to do something like STL, MFC, OWL or VCL then it is essential that you not bog down in the details. If you want to write something like Windows or DirectX it is also essential.
You haven''t explained why you should comment if you can get by without it.
Game development by nature is a pretty "flexible" process. Milestones are more concerned with making sure you're on the right track and have the contractual content.
