quote:Comments are only important if you want to maintain the code.
If you''re never going to program again, comments aren''t needed.

Care to back that comments are necessary for maintaining up?

quote:...
Comments are not supposed to describe whats going on, their suppose to tell why it''s going on. And the why is not conveyed by the best naming conventions.

Outside documentation is better for this, saying why applies to the general organization of modules.

quote:Hey pal, before you start getting punchy - I was _asked_ what my experience was. That''s the only reason I posted my credentials. And considering this is "gamedev.net" I think its relevant, especially while explaining my side of the argument. You''re the one posting anonymously. Perhaps you''d like to give us your relevant experience?

I''m The1Blade, sorry for the mistake.

quote:But you win. You''re super-I-don''t-need-to-comment-because-I''m-so-damn-good programmer man. I wish I could say I have that much skill. I don''t. Probably 99% of the programmers (skilled or otherwise) in the world don''t have that ability. ::shrug::

Where did I claim this?

quote:

''algorithmical errors'' take up more time than typos; debating that would be ludicrous. Commonality is debatable and irrelevant.

Algorithmical errors are just as easily fixable by examining the code as using the comments to figure out the problem.

quote:

Sometimes, yes, but it is irrelevant. You actually argued that the number of charecters was equal; I say find any professional code that has that property, and I would be very surprised.

If it isn''t then there aren''t enough comments to accurately describe every small algorithm or operation.

quote:

Theoretically, mabye, but in practice it is hard to modulize so well and keep them so small as to nearly eliminate the debugging process. As in, no team that I know of has ever been able to do so; they either have a long debugging period or they ship a buggy product. And I rarely make typos in my code (I do, just rarely), I generally don''t bother to fix them while writting online. I also don''t use variable names containing words I don''t know how to spell, as I sometimes use words I don''t know the exact spelling for; but It''s not worthwhile to look it up.

It''s not that hard to modularize like that. Give each algorithm a separate function or macro.

quote:

I questioned your professional experiance becuase you actually suggested: Don''t comment if your coworkers/boss ask you to, ''Manipulate'' your boss, and other things that sound liek you have no idea what you are talking about. I''m sorry if you find it insulting, but I continue to believe you have no professional (being paid for coding) experiance.

I am very insulted by your claim. Fact remains that I have 23 years of experience. With several different companies.

quote:

Objective (from dictionary):"Uninfluenced by emotions or personal prejudices". Not even close.

I didn''t use emotion in my 1st post. I examined each side.

quote:

Are you telling me it would be quicker to read the whole code than to read one line describing the return value?

No...you read the return statement.

quote:

Get a job, then mabye you can figure it out.

I have one...

quote:

But if it''s not? Comments are another layer of protection from the real world, where documentation may be inavailable, incomplete, nonexistant, wrong, etc. Stop being so damn theoretical and be realistic; you speak in "shoulds" and "ifs", welcome to the imperfect real world buddy. Also, it can be easier to just refer solely to code, and not both code and documentation.

I agree that if you have bad documentation, then I''d rather have comments, but I''d prefer you learn to document your code better instead of typing comments.

quote: Fight the good fight, buddy.

"Good fight?"

quote:You''ve hit it right on the head. In a perfect world, you''d need no comments because every function would be immediately understandable and obvious to anyone.

But good documentation is realistically possible.

quote:Software engineering at any kind of real scale is nowhere near the perfect world. Productivity comes at a premium. If you have to constantly be reading and guessing at possible functionality from a complicated set of code (and no, you _can''t_ say that with "proper" layout you can make all complexity irrelevant) - you''re wasting tons of time and adding tons of risk whenever you change a line of code. Programming without comments is like running your car without oil. You''re not going to get very far before the whole thing comes to a grinding halt of steam and busted bearings.

If something is complex enough that modularity can''t fix it by isolating individual sections, then you have as much luck undestanding the code through reading it as reading the comments.
If you read the comments only, you open yourself up for the comments not being consistent with the code, if you read and comprehend both, then you could''ve just read the code.

quote:So much for the ''objective analysis''

If you don''t see it as an objective analysis, then it''s not my fault.

quote:Commenting is important if your coworkers want comments because they won''t be happy without them and will get all upset like many people here It is not something worth fighting over. If I''m going to fight a fight then it is going to be over issues that cause defects to be introduced into production such as inadequate testing or operational costs to be excessive such as not knowing what they are doing. Also you have to teach them however you can and if all they will do is read the comments then that is the only tool you have other than setting with them while they code.

So you''re going to use up your own time for the benefits of people that take money from the company pool?

quote:Has Bush really won? (personally... well, he''d better or I think this country is in BIG trouble) They don''t actually know yet...

You like bush? Care to explain why? (i know it''s irrelevant but does that really matter? we can have this political debate by the side)

quote:I decalre that several-posts-ago the longest reply I''ve seen. I stopped reading at maybe 40%, and I doubt many ppl even got that far (tho'' I''m sure a few did).

I had to write it, you don''t want to know how I felt.

quote:Well, depending on the size of the project, and the time-constraints, you may not have the luxury of spending time figuring out your code again. Nomatter how good you write your code, it''s still going to take longer than reading your own pre-parsed text at the top of the function. Figure the code out once ( when it''s DONE! ), and then write it up in the code, then put it in the documentation ( note: I do NOT mean the user''s manual here, I mean the project documentation ), and then you could just as easily remove the comment from the code and refer to the documentation only.

So you need comments to understand code as you write it? Why?

quote:You can modularize your code and document these modules all you want (ie what they are supposed to do, how to use it, etc), but if someone has discovered a sneaky little trick in one of these modules to make a difference in performance (which in my expereince happens all the time) and implements it, there is a good chance that someone that is trying to debug this module will not be able to understand it without a bit of analysis. Here is a great place for a comment. If I can read a comment and know what the other programmer was thinking in a few seconds isn''t that better than spending several minutes/hours trying to figure out why they did what they did?

If they made a small algorithmical change, then they should tell you where they did it, and then you go and easily figure that one line out yourself.

quote:I really think a lot of people are getting a little picky. To me documentation and comments are part of the same thing: making it easier for someone else to understand how to use your code and how to fix it when there is a problem. I personally like the use of both but do agree that proper use of whitespace and formatting is a large issue as well.

Documentation is separate and should say why each module does what and how it is organized. If you need to understand a part of the code, the documentation will lead you to where the problem is and you can figure it out from the code.

quote:Another big point is that in my experience, it is usually the more experienced programmers/designers that design and write code, the less experienced that will do maintenance/debugging. In this case, it becomes much more important to properly document/comment your code.

Thanks for proving a point of mine, if the good programmers write the code, then it is properly modulized, etc. and the maintenance people could easily figure it out. The only thing that would take thinking are the more complex algorithms, which would take you the same amount of time to figure out with or without comments.

quote:daveb''s arguments have more credibility than yours. Have you written or published a major game? Have you coded for days and nights? When was the last time you worked at a company to claim "boss manipulation" is possible? I have not worked at any company, but do I claim anything as silly as what you say?

You are insulting me. I have worked in the computer industry for over 20 years, I have the experience of various programming worlds. I have done all of these things.

quote:If comments were as useless as you say, and if they wasted as much time as you say, they would be gone. The market is not a religious ground, nor is it a fanatic philosophy. What works, survives. What doesn''t, dies.

Not entirely. There are many useless parts of programming practices. Just because many people believe in the use of something does not mean that it''s usefull. The majority is not always right. Plus comments were developed long ago, where the simple machine and assembly code prevailed. Modularization was not a standard practice as it is now. There was no OOP. Comments made sense of the otherwise havoc of code of the earlier days.

quote:1) tops of module files, explaining what the entire file is for

Documentation is more formal and more efficient for this.

quote:2) 1 line per class, describing the class

The naming convention and organization of the class is better for this. Otherwise, documentation could do this.

quote:3) 1 line pre function, describing the function

You should have a good enough naming convention to make functions understandable.

quote:4) 1 line above long blocks of code, explaining what the block will do

You shouldn''t have long blocks if you modularize correctly.

quote:besides, just because you''re a programming guru, can you recognize absolutely every implementation of, say, the quicksort algorithm? i mean, what if you have some self-taught programmer who''s read about some sorting algorithm, but never been taught that "this algorithim is called quicksort"? now, i''m sure that this self-taught programmer wouldn''t be in the commercial world giving you code to work on, but i''d imagine that there''d havt to be some similar situations. dunno, i''m no guru, and some of you might be able to, but that''s just my humble opinion, and i''d rather see a little bit of commenting before the block of code that implements it

1) Most people can recognize quicksort when they see it.
2) If they didn''t know the word "quicksort" to symbolize such a sort, then they could still easily see the method involved if they learned a recursive algorithm prior to reading the sort.

quote:also, about the lexical vs. logical errors.
when i''m coding, typos are not nearly as frequent as when i''m say, e-mailing or replying on a post. because w/ text like that, i don''t really care. the e mail will still be understood by the reader, so will the post, but a lexical error in program will NOT be understood by a compiler, so i''m _MUCH_ more careful when i''m typing in an ide. i dunno, but i don''t get many typos in my programming that are error. the only time i could see it being a real problem anyway is if you''re using single character variables, or variables that differ by a single char (and that difference just happens to be your typo)

Everyone has a few of those silly syntax errors(forgot a } or a ; ). They are pretty frequent, especially if you have several thousand lines of code.

quote:Lexical errors are very rare in my code. I always have my brackets and braces balanced, I always put a semi colon where one is needed, and even after a struct definition, and I almost never put = when I should put ==. Lexical errors slowly become less and less common, and I can now type out some code and it will compile without modification. I automatically do semicolons.

They still happen, rare, but if you are tired and programming at the late evening, you might make such errors in your rush. And my argument that other logical errors could still be easily fixed because the code is fresh in your mind after you finish typing it and tested it.

This is The1Blade.

quote:Read the first few chapters of Code Complete, and you will find all the evidence you will ever need.

You don''t have any arguments yourself?

quote:You must be misunderstanding. Comments are useful for understanding a module line-by-line, something documentation is not as good for.

If you know what the module is supposed to do and you modularized correctlye(in which the module is sufficiently small), then you can understand each line.

quote:Wrong again. You can''t always figure out intent from the code alone.

What if the intent(aka what the comment says) is wrong?

quote:So your whole arguement rests on overboarding comments or none at all? I say there is a happy medium, where comments can help complex lines, or one breif comment can explain intent of multiple lines of code.

My argument does not rest on that. If a line is complex enough that you need comments for, then it would take the same amount of time. You''re going to need to understand both and the path from english to pseudocode to code is the same as code to pseydocode to english.

quote:Find me perfect code of a reasonable size by any professional team, then I''ll believe you. As far as I know, no such code exists.

So your argument is based on insulting the professional programming world?

quote:For arguements sake, let''s assume it''s 23 years professional programming experiance. I pity your poor job finding skills that get''s you stuck with boss''s you have to manipulate. And ignoring boss''s and coworker''s requests for your own ''happiness''? I''m sorry, but the small amount of ''happiness'' you may or may not gain is more than offset by the fact that those are acts of an asshole.

Business is never friendship, it is business, I do what I need to for my own well-being.

quote:No, you used personal prejudice. Is english your first language? Objective analysises are not arguements, they don''t come to conclusions. They don''t have personal opinion. Your first and all following posts had much of all.

I analyzed comments objectioinally. After the analysis I derived an opinion.

quote:Now, you may tell me that in a perfect world all functions have one return statement. But in reality, that is not always so. Not to mention that not all return statements in the real world are so descriptive that you can instantly understand what it''s returning solely from the line. This is a perfect place where comments can be helpful.

You can easily point out return statements and find out the reason for its existence by the statements that surround it.

quote:And you still don''t comment at the request of your coworkers/boss? No wonder Dilbert hits home for so many people.

If it would benefit me, I would. It happened before, and I wasn''t very happy from either result.

quote:Don''t tell me how well I document. I still claim that your whole arguement is based on a hypothetical world where everyone comments perfectly, uses perfectly understandble variable/function/class names, and other perfect programming styles. If you seriously have worked in ''several companies'' as a programmer, you would realize this.

It would benefit us to get better in organization, style, and nomenclature, rather than use comments.

quote:No, it can be more effiecient and quicker and easier to read and understand both.

Like I said before the amount of time to go from english to pseudocode to code is the same as the other way arouind for complex lines.

quote:Your right, it''s the fault of the english language to have defined ''objective'' differantly than you.

No, it''s the fault that you never learned what "objective" means.

quote:If the company asks me to, you''re damn right I will. Stop being so self-centered.

If they said that they would prefer it but you wouldn''t gain from it, would you? Im not being self-centered.

quote:You can join our ongoing political thread "Gore or Bush" in the lounge. It should be a few days old, but there''s some good stuff there.

Ok thanks, when I find time, I''ll go there.

quote:Um...are you kidding? Are you claiming they should stop whta they''re doing, interuppt you, both go to the line in question, have one explain it to the other? You are telling me this is better than a line of comment? What if the other is at lunch, sick, vacation, busy in a meeting? What if they don''t want to be interrupted every damn time a line of code changes in the project? I sure as hell don''t.

No, once the person gives something back with changes, they should outline what the major changes are and where the minor changes are and how they fit in witht he rest of the code.

quote:I want to hear more about this ''boss manipulation'' you''ve done. Do you search out jubs w/ impaired bosses or what?

No...Bosses are people, people can be manipulated. I use the general nature of humans to get the boss to consider me more important than the co-worker.

quote:Which bring up a good point...assembly is still used today. In fact it''s required for PS2 programming, which has already been mentioned. I again challenge anyone to understand uncommented, but documented, PS2 assembly code faster than one with comments. I bet the one with comments could understand it 50x faster, and that is probably underestimating.
This is from one that had to work with sparsly commented optimized assembly code, but well documented. I had to take out a pen and paper for illustration to really understand what was going on.

Obviously assembly and other such low-level languages will and should have comments because you can''t implement good programming style because of teh limitations of the language.

quote:Once again, that is a damn good function name if you can understand everything it should do from the name; including return value, what variable of the class it modifies, what functions are necessarily called before,etc.

The name tells the general organization, how it fits in teh general program. You can see what it modifies from the function itself, smae for the return value.

quote:So what? It is beyond ludicrous to claim that these will take up even comparable time to algorithmic changes.

the ratio is bigger than you think. Most algorithmical errors are quickly fixed in the after-module-made testing process.

quote:Wow, do you watch me code late at night?

No... this should be fairly obvious.

quote:Microsoft has a habit of code inconsistency. To date, however, their technologies have proven ubiquitous in the world of PC programming. Moreover, they are among the most resourceful of PC developers. Even if the last five years were nothing but a corporate battle, everything before had to be substantiated by something. So I disagree that commented MFC is not (at least) equal to eloquent VCL.

Why would they need to comment their own products for our benefit?

quote:
No, once the person gives something back with changes, they should outline what the major changes are and where the minor changes are and how they fit in witht he rest of the code.

I work on a project that contains over 20 million lines of code, and has code in it that''s nearing 15 years of age. Are you suggesting everytime I want to see why a certain line was added, I go digging through all the change logs?

i comment lightly. nothing annoys me more than watching a coworker change some code and purposely cut-paste the "expired" comment into (i guess) a proper place in the code.

so most of our project is littered with old comments that we kept because "they might still be valid", even when a half-retarded monkey could see that they''re not.

so i only sparsely comment. i only spend 1/10 of my time on average. no one complains. it works for me and my team.

just figured i''d throw my .02 cents in.


crazy166
some people think i''m crazy, some people know i am