Archived

This topic is now archived and is closed to further replies.

The1Blade

An objective analysis of comments: Are they necessary?

Recommended Posts

The1Blade    122
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)*

Share this post


Link to post
Share on other sites
Neurotic    122
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
----

Share this post


Link to post
Share on other sites
The1Blade    122
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.

Share this post


Link to post
Share on other sites
Silvanis    363
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.

Share this post


Link to post
Share on other sites
LilBudyWizer    491
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.

Share this post


Link to post
Share on other sites
Vetinari    133
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:
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

Share this post


Link to post
Share on other sites
Ironblayde    130
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.

Share this post


Link to post
Share on other sites
Jumpster    122
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

Share this post


Link to post
Share on other sites
LilBudyWizer    491
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.

Share this post


Link to post
Share on other sites
The1Blade    122
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.

Share this post


Link to post
Share on other sites
Guest Anonymous Poster   
Guest Anonymous Poster
I am of course just an evil anonymous poster, but.......

I think comments are making the code less readable and they make it look ugly!
I have an easier time reading the code cuz it has no typos and such things in it(you know you''ll get compiler errors when your syntax has typos).
I don''t like other people browsing thru my code they are just supposed to be users and look at at the interface(accessor funcs etc) they couldn''t understand it anyways
I think using 3rd party stuff isn''t good anyways it''s commercial everything that''s thought to be sold sometimes has to fit into schedules and so it''s released earlier cuz people do not only pay money no they also can do the debugging.
if it wouldn''t be commercial it''d be 99.9% bug free
if I would need to change major parts of it well what would be the point in using it then anyways??

Hmm writing a li''l prog that deletes the comments out of the code might be a usefull tool and for comment fetishes why not write program that let''s you look at your code in html style or something you could browse thru your comments && search for further information about the comment related topics and son on of course you''d have to use a scripting like comment style and you could put it on the net directly and everyone could read it maybe u could even sell it to others as reference to my main render loop and novel of the ai algorithm - Why those pesky little rats are more intelligent as npc''s in other games
Cheers

Share this post


Link to post
Share on other sites
daveb    122
If you ever hope to hold a real professional programming position of any kind you damn well better use comments.

If you don''t see why they''re useful, you''ve obviously never done anything above the complete tinker-toy level of beginning programming.

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.

Or suppose, you''re handed a pre-compiled library (common at many large development houses) and a header file with no comments? Hmm, can''t exactly rewrite the library now, can we?

You''re kidding yourself if

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.

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.

Do yourself a favor, ignore anyone who says comments aren''t worth it.

Share this post


Link to post
Share on other sites
daveb    122
quote:

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.



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.

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.

I _dare_ you to go into an interview for a programming position and tell your interviewers that you think commenting is basically pointless. They''d laugh so hard and your interview will be over so fast it''ll make your head spin.

Sure, work on toy projects and don''t use comments. That''s a brilliant way to prepare for the future when you''re doing something of any significance.

Share this post


Link to post
Share on other sites
Vetinari    133
quote:
Vetinari
1: You would be hard pressed to find code with the amount of text equalling the amounts of comments. So less than double space.
The1Blade
It happens often, when you have complex code that deal with various different parts, in various different ways, this does happen if you comment.


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.

quote:
Vetinari 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.
The1Blade
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.

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.

quote:
Vetinari 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.
The1Blade
I disagree. First of all, most errors are syntax errors, which you can easily and quickly fix without complex.


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?

It''s pretty obvious you have no real world experiance. When you get some, come back and we can discuss this further.

Mike

Share this post


Link to post
Share on other sites
Guest Anonymous Poster   
Guest Anonymous Poster
daveb yes you are so right at least from the commercial programmers point of view, but commercial programmers can''t be good programmers anyway since all they see is money and time schedules, and all they create is bugs and bugs if you would be programming for the joy of it you''d probably hate comments in your code(.c/.cpp) files a few headers might need comments but only a few (mostly belonging to dlls and libs).

Share this post


Link to post
Share on other sites
LilBudyWizer    491
The value of comments is inversely proportional to the experience of the programmer relative to the program being worked on and not the other way around. Do you really need a well commented "Hello World" program to understand? Perhaps you do, but my guess is no. Was that always true? I''ve been programming for about 20 years. Your experiences may vary, but I generally find what was complex to me five years ago isn''t today. Personally I find I get more experienced instead of the other way around, but that is because I keep programming. As you gain experience you learn to recognize patterns faster. If you have never done a quicksort then perhaps you won''t recognize one, but if you are an instructor reviewing a hundred of them a semester I doubt comments do anything except explain what the student didn''t understand and why they got it wrong. As a student you might well forget because you don''t have any use for it for several years because you use a utility or function instead. Under those circumstances I''m going to go to a book that explains a quicksort rather than looking at old code and the comments it contains even if I have to change the old code.

I find comments that only inexperience programmers don''t value comments to be offensive. I certainly appreciate explainations of how to do things I don''t know how to do, but I turn to a book for that, not source code. If I''m working with others then I would much prefer a seperate document with little things like block, state transition, entity relationship and data flow diagrams to understand it. The idea that the best way to understand a large complex application is to read all the comments seems at best naive to me. Personally I would like people to be perfectly honest here. How many arguing the merits of comments actually write any documentation for their programs? If you don''t then I must insist that it would be a better use of that 10% of your time to write the frigging documentation.

As for what I''m going to do one someone elses dime is a differant story. I''m either going to do what is demanded of me or decline the job. This wasn''t a question of what is demanded of you on your job. What was demanded of me the last year of my job was to set on my ass doing nothing while they debated for three months whether the cost was worth the benefit of me working for a week to cut a $100,000 from the annual cost of running the system. I have to question if anyone arguing the "professional" world is this happy, perfect place has any real experience. The "professional" world is full of people that cannot program, managed by people that have no idea what it takes to write a program much less the differance between a good program and a bad one. Comments is a simplistic concept they can grasp. Oh, comments is good so anyone that doesn''t comment is bad and anyone that does is good. Duh, the quality of a program is the quality of the code and not the comments. Comments are a nice to have if you have to work on a program beyond your skill level and the best comments in the world does not make up for a lack of program documentation.

Share this post


Link to post
Share on other sites
Guest Anonymous Poster   
Guest Anonymous Poster
that was a good post especially the last line: comments are ...
that reminded me sometimes i comment stuff for fun if i know someone else will read the source i put jokes in there for those people (i know who gets to read my code if anyone) that makes the code nice to read... heh we even decided to make something like a story out of those comments they should tell about stuff happening outside of the computer things like black holes suddenly appearing or your mouse getting eaten by a cat or maybe just a friend of yours bringing you a ''warez'' version of the game you just started programming!

Share this post


Link to post
Share on other sites
ImmaGNUman    122
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.

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.

Now, perhaps your style is good, and you plan never to change it. Comments are not to state obvious stuff. If you write, for example,

i++; // Add 1 to i

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.

(Being a taste of your own medicine)As for people who comment and comment over there comments, et etc. Well, I have the same argument you have been giving me about badly written code: No one should do that(End a taste of your own medicine)

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

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

Share this post


Link to post
Share on other sites
Vetinari    133
quote:
Original post by LilBudyWizer
I find comments that only inexperience programmers don''t value comments to be offensive.


If that''s directed at me...I think you misunderstood me. I never generalized to all, I was attacking his experiance becuase honestly I don''t find hist arguements well formed.

quote:

I have to question if anyone arguing the "professional" world is this happy, perfect place has any real experience. The "professional" world is full of people that cannot program, managed by people that have no idea what it takes to write a program much less the differance between a good program and a bad one. Comments is a simplistic concept they can grasp. Oh, comments is good so anyone that doesn''t comment is bad and anyone that does is good. Duh, the quality of a program is the quality of the code and not the comments. Comments are a nice to have if you have to work on a program beyond your skill level and the best comments in the world does not make up for a lack of program documentation.

Honestly, I have no idea what kind of experiance you have in the professional world, but I had no experiances like that. In both jobs, the higher ups either had programming experiance or let programmers make all programming decisions. Both demended of me moderate documentation of my code (comments). If you had a different experiance, that''s fine, I was just sharing mine.


Mike

Share this post


Link to post
Share on other sites
daveb    122
Heh. I''d wager this guy doesn''t have 20 years of experience. In fact, my rough estimate would be about, oh, zero.

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.

Its stupid. Do engineers layout car parts with just pictures, and leave out the dimensions and descriptions? No. There would be no cars.

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.

Share this post


Link to post
Share on other sites
Guest Anonymous Poster   
Guest Anonymous Poster
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?

Share this post


Link to post
Share on other sites
Guest Anonymous Poster   
Guest Anonymous Poster
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

Share this post


Link to post
Share on other sites
LilBudyWizer    491
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

Share this post


Link to post
Share on other sites
daveb    122
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

Share this post


Link to post
Share on other sites
gmcbay    130
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.




Share this post


Link to post
Share on other sites