There are numerous reasons to comment. Header like comments on that square function will show up in Visual Studios intellisence, so when you type in the function name it will give you a brief description of what the function actualy does. This helps in differentiating between many overloaded functions that may or may not do the same things based on the namespaces. Obviously square in this case means square a number but it could also be someone''s derrivation of the RECT structure in class form.
If no one ever sees your code except for you personaly I encourage you to avoid commenting. Put the code into a folder and come back in 2 years and try to figure out what the hell you were thinking when you made it. Especialy if your one of the programmers who gives their variables funny names like int foobar. Or char chode. You''ll have a bunch of useless code on your hands. Especialy if it''s something as extensive as a game.
As for those automatic comment generating utilities, those are even worse than not commenting at all. If the utility makes even one small mistake you''ve tricked the person reading the code which in most cases is yourself or those who know more than you and are smart enough to realize the mistake and how it was made.
Commenting is nessassary, they take up less time than trying to find a bug in your game, they are easy to write and never give you any compiler errors! In a world where you can write "Hello World" to the screen in over 50 diffrent ways why can''t people see that there is a need to comment? It explains what you did, and why you did them.
Joseph Fernald
Software Engineer
Red Storm Entertainment.
------------------------
The opinions expressed are that of the person posting
and not that of Red Storm Entertainment.
Code Comments
Joseph FernaldSoftware EngineerRed Storm Entertainment.------------------------The opinions expressed are that of the person postingand not that of Red Storm Entertainment.
Comments are suppose to describe the behavior or objective of a piece of code. Niether of which are apparent from the code itself - certainly not when there is a logical error (bug) in the code.
However, it''s ten times worse when the bug is in the comment.
Not commenting, or being overly protective of your code, in the interest of preserving your position makes you a liability (and not an asset) to the company you work for. It''s not as though you need to worry about finding a programming job in the current market.
Magmai Kai Holmlor
- The disgruntled & disillusioned
However, it''s ten times worse when the bug is in the comment.
Not commenting, or being overly protective of your code, in the interest of preserving your position makes you a liability (and not an asset) to the company you work for. It''s not as though you need to worry about finding a programming job in the current market.
Magmai Kai Holmlor
- The disgruntled & disillusioned
- The trade-off between price and quality does not exist in Japan. Rather, the idea that high quality brings on cost reduction is widely accepted.-- Tajima & Matsubara
here''s what I use for file comments:
Note how I made a log of all changes to the class, so that users can see what has changed since they''ve last seen the class. This is VERY VERY VERY important in multi-user groups.
Note also that the header lists all required classes/modules.
and here is a sample function header that I use:
note how I explain exactly what the function does, what each of the arguments mean, and what it returns. This is so the user is not left guessing what the function does, and can easily use the function WITHOUT being required to look at the code.
Here is a sample header for a data member of a class that I use:
explains explicitly what the variable does.
This example is more for maintinence of the class, since it is a protected member. The above two examples are more for the benefit of clients than modifiers of the class.
Comments inside the function declarations should only be used when explaining important or unclear parts of the code, and a general paragraph comment on a logical block of code is much better than a line by line synopsis.
Good commenting is the best thing a programmer can do. Don''t let your laziness cause you to do extra work trying to figure out what the code does.
===============================================
Have I no control, is my soul not mine?
Am I not just man, destiny defined?
Never to be ruled, nor held to heel!
|
Note how I made a log of all changes to the class, so that users can see what has changed since they''ve last seen the class. This is VERY VERY VERY important in multi-user groups.
Note also that the header lists all required classes/modules.
and here is a sample function header that I use:
|
note how I explain exactly what the function does, what each of the arguments mean, and what it returns. This is so the user is not left guessing what the function does, and can easily use the function WITHOUT being required to look at the code.
Here is a sample header for a data member of a class that I use:
|
explains explicitly what the variable does.
This example is more for maintinence of the class, since it is a protected member. The above two examples are more for the benefit of clients than modifiers of the class.
Comments inside the function declarations should only be used when explaining important or unclear parts of the code, and a general paragraph comment on a logical block of code is much better than a line by line synopsis.
|
Good commenting is the best thing a programmer can do. Don''t let your laziness cause you to do extra work trying to figure out what the code does.
===============================================
Have I no control, is my soul not mine?
Am I not just man, destiny defined?
Never to be ruled, nor held to heel!
This is my signature. There are many like it, but this one is mine. My signature is my best friend. It is my life. I must master it as I must master my life. My signature, without me, is useless. Without my signature, I am useless.
Well you know how people say there are two things you should never bring up in a converstation? That is religion and politics. (If no one has ever told that to you then God help us all
) Well i think there should be one more thing added to this list that people should never bring up in a conversation. That is "should code be commented or not." As you can clearly see, it can get out of hand. What i mean by that is some people start to get personal which just gets the argument even more heated. Now im not saying you shouldnt EVER talk about it. Certainly you must so new programmers will know that you should comment.
Personally, i think every one should comment. Im not saying comment things that can be clearly understood such as x = x + 1 but a good amount of explanation about how a particular functon or section of code works is just fine. Trust me, it WILL help you later on when you look at the code again and it will make your co-workers and boss happy. People you should always try to keep on your good side if ya know what i mean.
And no one can tell me that 10 years down the road they will still understand every line of code they have ever written like when they first wrote it. Nu uh. I dont think so.
Well theres my post-o-lovin' Thats enough for now.![](smile.gif)
-SirKnight
Edited by - SirKnight on May 2, 2001 8:21:45 PM
![](wink.gif)
Personally, i think every one should comment. Im not saying comment things that can be clearly understood such as x = x + 1 but a good amount of explanation about how a particular functon or section of code works is just fine. Trust me, it WILL help you later on when you look at the code again and it will make your co-workers and boss happy. People you should always try to keep on your good side if ya know what i mean.
![](smile.gif)
Well theres my post-o-lovin' Thats enough for now.
![](smile.gif)
-SirKnight
Edited by - SirKnight on May 2, 2001 8:21:45 PM
We had this war last year! ![](smile.gif)
I never comment. I don''t read other peoples comments.
I just read the code. The code does what it does. The
comments can say anything.
This view upset a lot of people last year. But I still think
its true.
So to all those who shall flame my botty...
![](tongue.gif)
![](smile.gif)
I never comment. I don''t read other peoples comments.
I just read the code. The code does what it does. The
comments can say anything.
This view upset a lot of people last year. But I still think
its true.
So to all those who shall flame my botty...
![](tongue.gif)
"I am a pitbull on the pantleg of opportunity."George W. Bush
May 03, 2001 02:06 PM
Duh. Why don''t you just say bad comments are a waste of time instead of all comments are a waste of time?
Duh? Duh.
Duh? Duh.
Tell me Duh. How do you know *when* the comments are bad?
How do you know if the people writing them have bothered to keep them updated? How do you know if they were even accurate in the first place. The best coders I''ve met can''t string two coherant words together.
The code does not lie.
"I am a pitbull on the pantleg of opportunity."George W. Bush
Apart from commenting for the sake of people (and myself) readin my code, I have another reason. Once I have written some code, I write comments which explain and then justify the code. Often it''s when I get to commenting my code I begin to realise mistakes and design flaws which I wouldn''t have realised if I hadn''t bothered to go through what the code does in English.
Simon PriceSi@VBgames.co.ukwww.VBgames.co.uk
quote:
Original post by Davaris
Tell me Duh. How do you know *when* the comments are bad?
How do you know if the people writing them have bothered to keep them updated? How do you know if they were even accurate in the first place.
Tell me Davaris, how do you know *when* variable and function names are misnamed? How do you know if the people writing them have bothered to keep them updated? How do you know if they were even accurate in the first place?
Just because comments can become out of date if a programmer doesn''t update them is not a good reason ditch them. If you believe it is, then I assume you name all of your functions and variables a1, a2, a3, since variable and function names can be abused just as much as comments.
quote:
Original post by Davaris
The code does not lie.
Nope, but code can lie about the programmers intent ... and without proper function names, variable names, and commenting how would you know what the code is supposed to do?
- Houdini
- Houdini
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement
Recommended Tutorials
Advertisement