Greenie sentences

[Sailor Jones]

I think anyone that has been doing this for awhile recognizes the value of comments. If I have to go back and modify something I wrote a year ago and I can't understand what I was attempting to do, then the job will be more difficult. If I can't understand what I did, then the chances of someone else figuring it out are slim. Comments provide a road map. If I think what I am writing will be difficult to understand the intention of, then I always put in comments. I don't write function headers, but target my comments to the specific areas that I think will need it.

[Thomas Eyde]

digital man wrote:

If you can't explain what you've done then you probably dodn't understand it

I'd say, if you can't read and understand what they wrote (coded), the code is already in a bad state and no comments can save it. I don't know about you, but I have to understand the code, not the comments, before I can do any changes.

[cmpenney]

I like the short descriptions in code myself. I typically don't have alot of problem following other's code and too much commenting just makes it harder to read IMO.

[Vidhya Narasimhan]

Here are my 2 cents on this topic. One method that is very effective is naming the variables and methods to be self descriptive. This, along with necessary comments to describe complicated logic has worked out well for our team. The comments say "why" instead of "how". Examples for naming: Orders.GetDetailedInformation instead of ord.GetDetInfo Employee.IsRetired instead of Emp.Retired

[Kenneth Kasajian]

You can always stare at a code long enough to figure out *what* it does. Comment the *why* -- that's harder to discern.

[scoy6]

Thomas Eyde wrote:

I'd say, if you can't read and understand what they wrote (coded), the code is already in a bad state and no comments can save it.

The problem with reading code is what to do when it's wrong. Comments should focus on the intention of the code not the implementation. Hopefully the two will match up.

[schleprock]

i agree with Graham, comments within header files should explain what the method does, how to use the method, the expected output, and (gasp) any side effects. header comments should not ever explain how the method does it's work. within source code, comments should explain the intent of the code as well as any assumptions. i absolutely hate comments such as the one Graham points out and for God's sake, if you change the code and the comments are not relevent or even worse, not correct, REMOVE THEM or CORRECT THEM. it just blows me away when people check in code with obsolete or incorrect comments. i'll get off my soap box now. schleprock :cool: "God only knows, and he ain't talkin'" David Lee Roth

[JohnMcPherson1]

I write comments... The rule of thumb I use is this: If it looks sufficiently 'tricky' then I comment it. If it looks real 'tricky' then I comment every line. Why? Because in 6 months when I have to go back and maintain it I really want to know, in a hurry, what it does... Regards, By the way, by sufficiently tricky I mean code that would take someone an hour to two to figure out. The real tricky stuff is code that the next programmer will wast a couple of days on, cut it out and write their own. Regards, John McPherson "Sufficiently advanced technology is indistinguishable from magic." Arthur C. Clark, inventor of the telecommunications satellite

[Thomas Eyde]

sKoi wrote:

Comments should focus on the intention of the code not the implementation

I think we both have to search for a very long time to find anyone who disagree. But, how often does this happen? Sooner or later, the code will drift away from the comments. I believe if you are that good, that your code always match your comments, and your comments are right on the spot, then you could drop the comments. Your code would be already be clean and self documenting.

[Owen Lawrence]

I would say that code that does not contain comments was almost certainly written by junior programmers, if not amateurs. It's a clear indication that this programmer hasn't been around the bend enough times yet to know how good his code isn't. Comments explaining what the code does aren't always useful, but I'd rather have them there in case the code doesn't do what the comment says, which clearly indicates a mistake was made. Comments that explain WHY the code is there are more important. Suppose there's a little bit of goofiness in the code, left sitting there by Fred a year before. While Joe programmer was adding a new feature, he spots it and cleans it up. Six months later a client comes back for some repeat business. Three months after that his new system is deployed, and horrors, the abstract problem they spent a week researching two years ago is back! Fred was promoted last Chrismas because of the awesome job he did, pumping out code for all and sundry and he never looked back. He parleyed that promotion into a VP role at CodeMonkeyStartup over in Europe. Joe took TWO weeks to replace that goofiness because he wasn't overly familiar with the code and had to rewrite six modules because they didn't make any sense to him at all the way they were. He got a mark on his performance review and in trouble with his wife for spending his anniversary evening at the office. I quit my first job shortly after my boss told me to remove all my comments from my code because the customer could see them. I never regretted it.

[kackermann]

If you've been programming long enough, you can read anything. That's why only beginners use lots of comments. Plus, comments have to be maintained too.