Vet - you''re my new hero Fight the good fight, buddy.

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.

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.

So much for the ''objective analysis''

They should add a fire to the icons to choose from...

Just in my own defense that last long one was not mine. Now for the two comments directed towards my posts in that post...

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.

Personally my view is that I have the program and that is all that matters. If I want to know what it does I run it. I have a little differant perspective than most because have mainly worked on other peoples code and my concern is how it runs. Production monitoring picked it out of a crowd so I know what program has a problem. Profiling told me what section of the program has a problem. I then work my way out from there. First that section, then the purpose of that section in the overall program, then that program in the overall system. The equivalent of what I do is hacking. That is what I did before I got a real job. I unlocked copy protected software. Would you seriously argue to a hacker that he can''t hack a program without the source when they spend most of their time running the program, disassembling it and running diffs on the output. If so then you are most likely one of those people that think they can outsmart every hacker in the world when they have complete control of the system your application runs on.

I''m cross refrencing this thread.

Do You Comment?.

==============================
"Need more eeenput..."

- #5, "Short Circuit"
==============================

self=rand(); //

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

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).

free(sefl);
self=NULL;
DoSomethingUseful();
return 0;

--Tr][aD--

I just realised a difference between the situation in which most ( or all ) of you code, and the way I code.

My actual source code becomes part of the "documentation" as well, because I develop graphics techniques. I document/comment a lot in my own code, both for layout and for explanation. A lot of the time, the comments exist before the code - referring to paragraphs in my documentation, and copying the pseudocode for reference and so that I get the algorithm right the first time.
Other people will be examining my code along with the documentation, trying to learn from it.


Though, when I say I comment a lot - that''s NOT one line of comments per 10 lines of code at all. Most of my .cpp files are pretty sparsely populated with comments. A good design and descriptive variable names will remove almost all ambiguity in code, and even more so if it is "standard" user interface code, and not deep algorithmic code. There isn''t all that much deep algorithmic code in most projects, and creating a 15-line comment for a complex CreateWindow is overkill, because the people who are looking at that function generally know how it will be layed out and what they might expect.



Okay, the anonymous poster took a lot of time answering, so I''ll pick up on the quote he pulled from my previous message:
why should you write comments in your code if you haven''t done the documentation yet?

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.


The example I always think of is the MESA source code.
I think it has about 2 pages of documentation, laying out which modules do what with which other modules, when it isn''t obvious from the naming. It''s not a small project, but just that amount of documentation does just fine in allowing a programmer to edit the necessary source in just a few days.
I know, because I did it. I rewrote it so that it saves depth information along with an image.



People might not remember what you said, or what you did, but they will always remember how you made them feel.
~ (V)^|) |<é!t|-| ~

One thing that I haven''t seen mentioned is optimization. I am a professional software developer. I work in a company that develops large Oracle applications and play with game programming in my spare time (what little there is of that).

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?

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.

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.

And in case anyone flames me for posting anonymously, I''m not doign it on purpose. I''m on a different machine and after having not had to type in my username/password for a while now, I''ve forgotten it . Maybe I will fix this when I get home.

Bret.

The1Blade,

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? The argument here is rooted in the greatest minds - the minds that invented programming. Do you know the primary rule of marketing? If not, I will restate it to you. Supply and demand . 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.

I, for one, trust others'' credentials. Unless and until you prove to me with a certificate that you are more experienced than the others, who, I do not doubt, can prove their experiences as quickly as I can say, "Bob''s my uncle", I see no ground to trust your arguments.

Cheers. :D

The commenting style recommended by both Steve McConnell( "Code Complete" and "Rapid Development" ) and Bjarne Stroustrup ( the dude made c++, and wrote "the C++ Programming Language" ) is simple, efficient, and doesn't take any more time than naming your functions, if you really understand what they're suppossed to do.

basically, the only places you comment are:

1) tops of module files, explaining what the entire file is for
2) 1 line per class, describing the class
3) 1 line pre function, describing the function
4) 1 line above long blocks of code, explaining what the block will do

now, these comments are IN ENGLISH, not even really pseudo-code. they describe the intent of the block, not the mechanics of the implementation of it

Stroustrup's rule of thumb, don't comment what's clear in the code.

you would never comment like this
*Dest++ = *Source++; // copy source to dest
because it's just redundant
that leaves out a lot of the commenting, i'd say

in a nutshell, if you have to comment more than that, you need to rewrite your code to make it clearer.

short, consice, explicit
that's what i say.
comment comment comment

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

i agree that comments should not be, in any way, a substitute for any formal documentation of the code. I just feel they should supplement it, and that they are both necessary.

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)

phew! sorry, got really long winded there, but i feel better now

-Succinct

p.s. McConnell actually suggests using pdl as your comments, but he also stated that it was unrealistic in some situations, and went on to suggest a style similar to strostrup

p.p.s. as for this anon. poster:

quote:

---

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).

---

what, are you fourteen, and full of teenage angst, hating all of that which 1) you cannot understand, and 2) cannot achieve?

do you think that everyone on here that's a good programmer is NOT a commercial programmer, and that every bad programmer IS?

i bet you're pretty terrible, and that you're not commercial.

i've been programming for 7+ years, between 20 and 50 hours a week, and it's never been for a job, not once. I comment, and how could i NOT love programming if i've been doing it for 7 years w/o pay?

not a job yet (shameless plug shameless plug shameless plug)

comment comment comment

//////////////////////////////

I have no name that you may call me. I am Succinct, so call me as such.

\\\\\\\\\\\\\\\\\\\\\\\\\\\\Edited by - Succinct on November 17, 2000 10:53:39 AM

Edited by - Succinct on November 17, 2000 10:56:57 AM

Edited by - Succinct on November 17, 2000 11:33:48 AM

lol

Windows.h has alwasy been well commented.

lol hee ehee

microsoft does it, so shouldn''t we as programmers all do it as well?

lol haaahaaahaaahaaa

microsoft
bwaaaaaaaaaaaa haa haa haaaa

microsoft commenting
haaaahaaaahaaa bwughaaaaaa aahaa ahaaahaa
rofl

sorry, ms flame

//////////////////////////////

I have no name that you may call me. I am Succinct, so call me as such.

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\