An objective analysis of comments: Are they necessary?
Author
I know what you''re thinking: "Who is this lunatic trying to question one of the most popular aspects of coding style?"
Hear me out. Read my whole post before replying, do us both a favor.
Now, let''s begin.
First let''s examine the arguments of both sides.
Why do some people not support comments?
They same it is a waste of time.
The "waste" part is an opinion, so let''s just consider their argument as "They take up a lot of time"
Now why do people support comments?
So your co-workers or you in the future can understand your code.
Now let''s analyze whether or not these points are valid.
How does it take up a lot of time?
This one''s a no-brainer. To adequately comment code(especially a game engine) you''re going to need to take up double amounts of text as without comments. This makes it that it will take up double amount of time.
Now why is that it helps your future self an invalid argument?
Because you don''t need to understand your code. If you need to change data, you probably have a file of #defines for that. Just change that. If you need to change an algorithm or rework any other part of it, then you still don''t need to comment. If you followed principles of modularity in your product, then you can easily just change small parts of it that you need. If you need to rework the whole thing, just expand upon the program via derivation, or other methods(this is especially true for game engines made for COM).
Now about your co-worker. You have less amount of time to live your happy life, for someone that shares from your company''s money? If he''s happy, won''t he be able to work on other things increasing in rank? This is a selfish reason, but realistically, is the happiness of person that can practically take money away from you worth losing your time?
Comments/Questions?
*prepares flame-protection gear(aka hiding behind some stranger)*
Here''s an idea for you.
You don''t comment.
Your co-workers dislike you.
co-workers ask you to comment.
You refuse, stating above reason.
co-workers really don''t like you.
This makes you life at work less than enjoyable.
You still refuse to comment.
co-workers start to hate you, and this travels up to management that you refuse to be a "team player" and are basically annoying the hell out of your co-workers.
Management dislikes you...
...eventually making you lose your job.
Comment.
Makes everyone''s life easier. Including your own.
That is of course, if you don''t like being unemployed.
Mark
----
www.emanatemultimedia.com
----
You don''t comment.
Your co-workers dislike you.
co-workers ask you to comment.
You refuse, stating above reason.
co-workers really don''t like you.
This makes you life at work less than enjoyable.
You still refuse to comment.
co-workers start to hate you, and this travels up to management that you refuse to be a "team player" and are basically annoying the hell out of your co-workers.
Management dislikes you...
...eventually making you lose your job.
Comment.
Makes everyone''s life easier. Including your own.
That is of course, if you don''t like being unemployed.
Mark
----
www.emanatemultimedia.com
----
Author
Bosses will see that THEIR work is late and since they really care only about the general production they will think that your co-workers are just trying to avoid doing their part of the job. Bosses DON''T LIKE to hear complaints too. They will get annoyed at your co-workers.
If there is a meeting with co-workers, you and your boss just say that there are too possibilities: "comments" or "on time"
You can manipulate your boss this way.
If there is a meeting with co-workers, you and your boss just say that there are too possibilities: "comments" or "on time"
You can manipulate your boss this way.
Why comment? I can think of a couple of reasons, both of which have nothing to do with helping your co-workers : )
Take this for example:
You''ve been working hard at your program for 6 months. You are finally doing a thorough bug-testing/QA stage, and you come across an error in a module you did early on. Now, since it isn''t commented, you spend 5 minutes scratching your head saying to yourself "How am I doing this again?" whereas with comments it shouldn''t take you more than a minute. So you''ve gained at least 5x the productivity as opposed to the 2x effort in commenting (which assumes two things: one, that you''re commenting every line, which is excessive; and two, that bug-testing/fixing takes up a significant portion of your coding time, which it generally does)
Seconding, breaking down a large project for modulatiry purposes is going to require writing down information somewhere. At the very least, in order to keep a black box principle with your functions, you need to comment what they do in the declaration. So why not have this information in the code? You can write a function in PDL and use that for your commenting. Not only are you making commenting more efficient since it''s also part of your planning stage, you are giving yourself a buffer to catch higher-level errors in your thinking before you get into the nitty-gritty implementation details that might hide such things.
The idea that "you don''t need to understand your code" is wishful thinking, IMO. Even if you use other good programming practices, you still run into problems with code reuse. After all, a function that seems to have a perfectly clear name while you write it may end up becoming obscure when you''re looking for things to reuse. Assumptions made while creating it may not be true due to program changes or when it''s used in another project.
All in all, the time hit in the beginning to make comments (note that I say nothing about putting comments in after you''ve written the code) well be well worth it later on, especially with larger projects (read: games), when trying to re-use your code, and when squashing those pesky bugs that didn''t show up right after designing the function/module/class/whatever.
Take this for example:
You''ve been working hard at your program for 6 months. You are finally doing a thorough bug-testing/QA stage, and you come across an error in a module you did early on. Now, since it isn''t commented, you spend 5 minutes scratching your head saying to yourself "How am I doing this again?" whereas with comments it shouldn''t take you more than a minute. So you''ve gained at least 5x the productivity as opposed to the 2x effort in commenting (which assumes two things: one, that you''re commenting every line, which is excessive; and two, that bug-testing/fixing takes up a significant portion of your coding time, which it generally does)
Seconding, breaking down a large project for modulatiry purposes is going to require writing down information somewhere. At the very least, in order to keep a black box principle with your functions, you need to comment what they do in the declaration. So why not have this information in the code? You can write a function in PDL and use that for your commenting. Not only are you making commenting more efficient since it''s also part of your planning stage, you are giving yourself a buffer to catch higher-level errors in your thinking before you get into the nitty-gritty implementation details that might hide such things.
The idea that "you don''t need to understand your code" is wishful thinking, IMO. Even if you use other good programming practices, you still run into problems with code reuse. After all, a function that seems to have a perfectly clear name while you write it may end up becoming obscure when you''re looking for things to reuse. Assumptions made while creating it may not be true due to program changes or when it''s used in another project.
All in all, the time hit in the beginning to make comments (note that I say nothing about putting comments in after you''ve written the code) well be well worth it later on, especially with larger projects (read: games), when trying to re-use your code, and when squashing those pesky bugs that didn''t show up right after designing the function/module/class/whatever.
I don''t do it for job security. Just kidding, but I seldom comment. Personally I feel that if you are going to have others working on your program then you should produce a programmers guide and not make them search through your code for bits and pieces of it. A well written programmers guide beats a well commented program every time in my book. Second I rewrite vast sections of my program while working on it. Simply put I don''t want to waste my time on comments that are going to be deleted and replaced with more comments. If I''m going to comment it is going to be at the end. That brings up the next point which is that there are very few people that will pay you to comment your program. When the program is ready for production they don''t want to wait for you to comment it. They want you to work on the next program and not spend your time commenting the program. So if they don''t think it is worth pay for then why is it worth my time to do. Finally in a program that is worked on by many people the comments are seldom maintained. That is a pure fact. At best they will add comments. That leads to misleading comments in the code. I can''t count the number of times someone has argued, but the comments said. It doesn''t matter what the comments did, it matters what the code did. That is why I strip all comments before working on someone else''s program. I don''t want to make the same mistake they did when they coded it because the comments told me what they intended. A good example is & versus &&. Looking at the code I see a bitwise and and a logical and, but reading their comments I might see a bitwise and where there is a logical and.
I think it is far more important to put plenty of white space in the code to break up the logic, keep functions small and to the point, good variable names, use structured programming, use modular programming and use object oriented programming than to put a much of comments into convoluted code. Make your program readable and simple to understand and most of the need for comments drop out. Saying you are going to loop from the start of the array to the last active element is a pointless comment and just makes it harder to read the code and follow the logic. Comments do not make up for poor programming practices and are in my opinion far less important than using good programming practices.
I think it is far more important to put plenty of white space in the code to break up the logic, keep functions small and to the point, good variable names, use structured programming, use modular programming and use object oriented programming than to put a much of comments into convoluted code. Make your program readable and simple to understand and most of the need for comments drop out. Saying you are going to loop from the start of the array to the last active element is a pointless comment and just makes it harder to read the code and follow the logic. Comments do not make up for poor programming practices and are in my opinion far less important than using good programming practices.
Obviously there are two extremes to this issue: No comments at all, and paragraphs of comments per line of code. A simple arguement against your extreme is that extreme views/idealisms rarely work in the real world at all.
Now for more specific issues:
1: You would be hard pressed to find code with the amount of text equalling the amounts of comments. So less than double space.
2: Comments don''t require as much thought or planning as the code, therefore it should not take as much time if you comment a line after you have written it.
3: Comments don''t require debugging, which most will say takes more time than actually writting the original code. So now we see percentage of time writting comments decrease significantly. Not to mention that studies show that comments in large products significantly decrease debugging/maintenance stages (see code complete). For me, commentang doesn''t even take %10 of my time, and probably saves considerably more than that.
I''m curious, do you or have you ever held a programming job? You don''t seem to have a clue about the workplace (I''ve only worked at two different companies though, so what do I know). You talk about ''happiness'' and ''boss manipulation'', but I don''t understand how this fits into your arguements about comments. Writting uncommented code at either of my jobs was completely inacceptable and not even considered.
Mike
Now for more specific issues:
quote:
To adequately comment code(especially a game engine) you''re going to need to take up double amounts of text as without comments. This makes it that it will take up double amount of time.
1: You would be hard pressed to find code with the amount of text equalling the amounts of comments. So less than double space.
2: Comments don''t require as much thought or planning as the code, therefore it should not take as much time if you comment a line after you have written it.
3: Comments don''t require debugging, which most will say takes more time than actually writting the original code. So now we see percentage of time writting comments decrease significantly. Not to mention that studies show that comments in large products significantly decrease debugging/maintenance stages (see code complete). For me, commentang doesn''t even take %10 of my time, and probably saves considerably more than that.
I''m curious, do you or have you ever held a programming job? You don''t seem to have a clue about the workplace (I''ve only worked at two different companies though, so what do I know). You talk about ''happiness'' and ''boss manipulation'', but I don''t understand how this fits into your arguements about comments. Writting uncommented code at either of my jobs was completely inacceptable and not even considered.
Mike
The idea that commenting doubles your development time doesn''t seem to be very well thought out. I don''t know about you, but I can generate relevant English a lot faster than I can generate optimized C++ code. The code takes a considerable amount of planning and logic in order to implement well. The comments take a few seconds each because you know exactly what the code you''re writing at the time is supposed to do.
You also only mention a few aspects of changing code: changing data and updating algorithms. In these cases, you''re right, commenting is less important. What if you need to implement a major change in how the code works? What if the testing stage of your game reveals that yor interface isn''t nearly as user-friendly as you thought it was and you have to rework some major aspect of gameplay? What if you license a third-party engine and want to strip it down so you can rebuild parts of it to fit your needs? What if you can''t find an elusive little bug and want to ask a knowledgeable co-worker to give you a hand? What if one of your non-commenting employees leaves the project before it''s completed? I hope you have fun trying to work out just how in the hell his incomplete, project-critical code is doing what it does.
These are only a few examples of where commenting will save you a lot of headaches.
-Ironblayde
Aeon Software
The following sentence is true.
The preceding sentence is false.
You also only mention a few aspects of changing code: changing data and updating algorithms. In these cases, you''re right, commenting is less important. What if you need to implement a major change in how the code works? What if the testing stage of your game reveals that yor interface isn''t nearly as user-friendly as you thought it was and you have to rework some major aspect of gameplay? What if you license a third-party engine and want to strip it down so you can rebuild parts of it to fit your needs? What if you can''t find an elusive little bug and want to ask a knowledgeable co-worker to give you a hand? What if one of your non-commenting employees leaves the project before it''s completed? I hope you have fun trying to work out just how in the hell his incomplete, project-critical code is doing what it does.
These are only a few examples of where commenting will save you a lot of headaches.
-Ironblayde
Aeon Software
The following sentence is true.
The preceding sentence is false.
I spend a considerable amount of time commenting my code.
However, I will say that I am a perfectionist by nature when it comes to my code. The content of the comments is not what takes me so long but the formatting of the comments does.
All of my bosses and co-workers have never minded the additional time it took for me to comment my work. In fact, my commenting style became required coding practice at work because of the time it saved in future revisions. If it takes me X amount of time to code something, I expect to take roughly 1/2X amount of time to document when, why, what was done and all other aspects of the program it will *likely* affect.
I don''t mind commenting my code because to me, it''s part of the QA process. I review the comments to make sure the function does what it''s intended to do and update as needed.
Regards,
Jumpster
However, I will say that I am a perfectionist by nature when it comes to my code. The content of the comments is not what takes me so long but the formatting of the comments does.
All of my bosses and co-workers have never minded the additional time it took for me to comment my work. In fact, my commenting style became required coding practice at work because of the time it saved in future revisions. If it takes me X amount of time to code something, I expect to take roughly 1/2X amount of time to document when, why, what was done and all other aspects of the program it will *likely* affect.
I don''t mind commenting my code because to me, it''s part of the QA process. I review the comments to make sure the function does what it''s intended to do and update as needed.
Regards,
Jumpster
I spoke from a perspective of having been the technical architect on a 2 million line system with 5,000 programs and 50 programmers. Mainly I did performance monitoring, tracking and reporting, but I was also the debugger of last resort. Anyone else could say they couldn''t find it, but I couldn''t. My job depended upon being able to fix any bug or performance problem because I am not a team player, I roll into work about noon, leave at 6, look like a harley rat and could care less what management thinks. There is only one reason I didn''t get fired and that is that when my bosses ass was on the line I saved it.
I will admit that if I had of been in a position where I was not the top technical talent then perhaps I would have viewed comments differantly. Since that was not the case if I didn''t understand how a section of code worked I just stepped through it with a debugger. Most often finding a bug is simply a matter of tracing it back from the evidence of a bug. A program crashs, you capture a dump and follow the stack back to the code. You look at the line of code, the values it is using and determine why that caused a crash. Then you look at everywhere that set the variable for the one that set it to the wrong value. If you have a sequence of operations that produce a wrong result you follow the input or the output. You don''t read the entire program. You spend an hour or two and fix the problem, not the next several months.
As for comments not exceeding code that is a joke. I''ve worked on programs that were 80% comments. The reason is that people comment out code while doing revisions. They also add comments instead of revising them. Some even comment out code, make comments about why they did that, add code and comments about why they did that, find it doesn''t work and comment it out, comment why they did that, then put in more code with comments about that and I think you get the picture. Within a large production system with a large number of programmers program documentation is far more important. You also have to have subsystem documentation and system documentation. You also have to have generic documentation that covers general concepts used within the system so that new programmers can get up to speed quickly. This includes items such as style guides, naming conventions, source organization and most importantly to me descriptions of common problems and there resolution. That last is so they don''t change code that fixed a problem because they don''t understand either the problem or its resolution.
I will admit that good comments are better than no comments. It is just that bad comments are worse than no comments and you are far more likely to get bad comments in a large system with many programmers. Also what is good comments for one person is bad comments for another. I want comments that are few and far in between. If a function implements Bresenham''s line drawing algorithm just tell me that. I have five books that explain it in detail. Don''t try to explain the algorithm and provide a proof for it in the code. If you are worried about whether I have a referance then put a detailed explaination in the program documentation. If the name of the routine is DrawLine then I most likely don''t need you to tell me what algorithm you used either. All that I need to know is that you are drawing a line. Now if it is just Draw with parameters of a rectangle and a flag saying draw a circle, rectangle or line, you mixed all the code together then it is going to be hard to understand, but not because you didn''t comment it. Rather it will be because you wrote convoluted code.
I will admit that if I had of been in a position where I was not the top technical talent then perhaps I would have viewed comments differantly. Since that was not the case if I didn''t understand how a section of code worked I just stepped through it with a debugger. Most often finding a bug is simply a matter of tracing it back from the evidence of a bug. A program crashs, you capture a dump and follow the stack back to the code. You look at the line of code, the values it is using and determine why that caused a crash. Then you look at everywhere that set the variable for the one that set it to the wrong value. If you have a sequence of operations that produce a wrong result you follow the input or the output. You don''t read the entire program. You spend an hour or two and fix the problem, not the next several months.
As for comments not exceeding code that is a joke. I''ve worked on programs that were 80% comments. The reason is that people comment out code while doing revisions. They also add comments instead of revising them. Some even comment out code, make comments about why they did that, add code and comments about why they did that, find it doesn''t work and comment it out, comment why they did that, then put in more code with comments about that and I think you get the picture. Within a large production system with a large number of programmers program documentation is far more important. You also have to have subsystem documentation and system documentation. You also have to have generic documentation that covers general concepts used within the system so that new programmers can get up to speed quickly. This includes items such as style guides, naming conventions, source organization and most importantly to me descriptions of common problems and there resolution. That last is so they don''t change code that fixed a problem because they don''t understand either the problem or its resolution.
I will admit that good comments are better than no comments. It is just that bad comments are worse than no comments and you are far more likely to get bad comments in a large system with many programmers. Also what is good comments for one person is bad comments for another. I want comments that are few and far in between. If a function implements Bresenham''s line drawing algorithm just tell me that. I have five books that explain it in detail. Don''t try to explain the algorithm and provide a proof for it in the code. If you are worried about whether I have a referance then put a detailed explaination in the program documentation. If the name of the routine is DrawLine then I most likely don''t need you to tell me what algorithm you used either. All that I need to know is that you are drawing a line. Now if it is just Draw with parameters of a rectangle and a flag saying draw a circle, rectangle or line, you mixed all the code together then it is going to be hard to understand, but not because you didn''t comment it. Rather it will be because you wrote convoluted code.
Author
quote:You''ve been working hard at your program for 6 months. You are finally doing a thorough bug-testing/QA stage, and you come across an error in a module you did early on. Now, since it isn''t commented, you spend 5 minutes scratching your head saying to yourself "How am I doing this again?" whereas with comments it shouldn''t take you more than a minute. So you''ve gained at least 5x the productivity as opposed to the 2x effort in commenting (which assumes two things: one, that you''re commenting every line, which is excessive; and two, that bug-testing/fixing takes up a significant portion of your coding time, which it generally does)
things that you won''t understand are all probably going to be algorithms, and not api calls, etc. right?
If you modularize(or is it modulize, or is it not a word?) correctly, then the code for the algorithm will be in one separate function. This makes it easy for you to examine the code, interpret it as pseudocode, and figure from there what you did. Unless you have long detailed comments for the algorithm, most likely the comments will just tell you the basic pseudocode, which you can easily figure out anyway, unless you have long comments, it''s probably not going to tell you why you did each small thing. If you do have long detailed comments, then the time in which you wrote them is more than the time you spend figuring the code out.
quote:Seconding, breaking down a large project for modulatiry purposes is going to require writing down information somewhere. At the very least, in order to keep a black box principle with your functions, you need to comment what they do in the declaration. So why not have this information in the code? You can write a function in PDL and use that for your commenting. Not only are you making commenting more efficient since it''s also part of your planning stage, you are giving yourself a buffer to catch higher-level errors in your thinking before you get into the nitty-gritty implementation details that might hide such things.
Why do you need to write it down?
And why do you need to comment what functions do? You should have a descriptive name for them.
quote:I think it is far more important to put plenty of white space in the code to break up the logic, keep functions small and to the point, good variable names, use structured programming, use modular programming and use object oriented programming than to put a much of comments into convoluted code. Make your program readable and simple to understand and most of the need for comments drop out. Saying you are going to loop from the start of the array to the last active element is a pointless comment and just makes it harder to read the code and follow the logic. Comments do not make up for poor programming practices and are in my opinion far less important than using good programming practices.
Amen, brotha
quote:1: You would be hard pressed to find code with the amount of text equalling the amounts of comments. So less than double space.
It happens often, when you have complex code that deal with various different parts, in various different ways, this does happen if you comment.
quote:2: Comments don''t require as much thought or planning as the code, therefore it should not take as much time if you comment a line after you have written it.
I disagree. Code is less characters first of all. And the logic behind it doesn''t matter. When you make a string of code, you KNOW EXACTLY what you need to know, you know exactly what you want to right in a certain loop, if statement, or even a large algorithm. You wouldn''t just start something and write capriciously from there.
quote:3: Comments don''t require debugging, which most will say takes more time than actually writting the original code. So now we see percentage of time writting comments decrease significantly. Not to mention that studies show that comments in large products significantly decrease debugging/maintenance stages (see code complete). For me, commentang doesn''t even take %10 of my time, and probably saves considerably more than that.
I disagree. First of all, most errors are syntax errors, which you can easily and quickly fix without complex. About logical errors, after you finished your code, it''s still all fresh in your mind. And you wouldn''t simply make a huge thing that took days and only compile it then. No, you compile modules separately, and test them from the main program. They are still fresh in your mind, so you still know exactly what you did in there.
quote:The idea that commenting doubles your development time doesn''t seem to be very well thought out. I don''t know about you, but I can generate relevant English a lot faster than I can generate optimized C++ code. The code takes a considerable amount of planning and logic in order to implement well. The comments take a few seconds each because you know exactly what the code you''re writing at the time is supposed to do.
Code says the exact syntax of a language. Comments say pseudocode. Hence before you write a string of code with comments, the planning involves thinking of both the pseudo and real code.
quote:What if you need to implement a major change in how the code works?
You make a new module and replace it with the old one.
quote: What if the testing stage of your game reveals that yor interface isn''t nearly as user-friendly as you thought it was and you have to rework some major aspect of gameplay?
Again, you don''t change the code here, you replace major parts of it that should be placed in modules.
quote:What if you license a third-party engine and want to strip it down so you can rebuild parts of it to fit your needs?
Same applies here.
quote:What if you can''t find an elusive little bug and want to ask a knowledgeable co-worker to give you a hand? What if one of your non-commenting employees leaves the project before it''s completed? I hope you have fun trying to work out just how in the hell his incomplete, project-critical code is doing what it does.
The co-worker is happy and you aren''t, this is from the original designer''s point of view, you''re not the one that has the choice in writing comments or not in the situation you described.
And besides, you can easily find the bug if your co-worker exercised modularity correctly.
quote:If it takes me X amount of time to code something, I expect to take roughly 1/2X amount of time to document when, why, what was done and all other aspects of the program it will *likely* affect.
I doubt this. I explained this before, but write your comments and code at roughly the same time, and you already know exactly what you need to do for each string of code and comments, making what really matter is the amount of characters you type.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement
