Greenie sentences

[Christopher Duncan]

Hey, if it was hard to write, it should be hard to understand! :-D Author of The Career Programmer and Unite the Tribes Know someone who desperately needs to get a clue? Visit www.DownloadAClue.com and send them one!

[Shog9 0]

I can read most of the languages i work with well enough - it's nothing but an annoyance to find that someone has documented the obvious stuff ("loop on each member of aObArray"). What i like to see are a) documentation prior to each method, describing both the reason for its existence and how it should be used, and b) documentation for bits of non-obvious code (not necessarily complex code, just code that doesn't exist for any internal reason - the sort of stuff we kindly refer to as "business logic").

---- Scripts i’ve known... CPhog 1.0.0.0 - make CP better. Forum Bookmark 0.2.5 - bookmark forum posts on Pensieve Print forum 0.1.2 - printer-friendly forums Expand all 1.0 - Expand all messages In-place Delete 1.0 - AJAX-style post delete Syntax 0.1 - Syntax highlighting for code blocks in the forums

[Shog9 0]

Heh, right on. I should have read your comment before replying. :)

---- Scripts i’ve known... CPhog 1.0.0.0 - make CP better. Forum Bookmark 0.2.5 - bookmark forum posts on Pensieve Print forum 0.1.2 - printer-friendly forums Expand all 1.0 - Expand all messages In-place Delete 1.0 - AJAX-style post delete Syntax 0.1 - Syntax highlighting for code blocks in the forums

[El Corazon]

I am a big one on documenting function intent. Sure the programmer can read the code and find out what it "is" doing eventually. But what did the programmer intend it to do? In a perfect world, the two always match. But what if there is a sideaffect because the function shared an input object in write form. It might work fine until someone else tries to manipulate the same variable, thus are bugs born. But if you didn't know that the programmer originally "intended" that parameter to be read-only, you wouldn't realize there is a bug lying and waiting. I guess programmers tend to look at comments with different intent. Some are using comments so their managers (non-programmers) can read the program. Others are using line comments to match an approved psuedo-code that is part of the design documents. Then there are those who look at header comments as the be-all-end-all of documentation, you don't even need to pull up the code, it's all laid out in the header along with flow-chart symbols, mathematical formulas, sample code sections, help desk numbers, and the date and time in 10 languages. Intent is the reason. Are your comments your published documentation extracted via doxygen? I have seen some pretty fancy doxygen comments! whew! My intent in comments is to put down my initial intent in the logic of the code, what is its purpose, what is its input and output functionality. Admitedly I come from the military IPO documentation standard days, so I have a bias. Still, I find the logic of documenting purpose worthwhile. Line logic comments are only for state oddities // Transmission loss detected // bad packet, estimate position for max xx seconds // this is a panic condition: initiate self-destruct But again, it comes down to intent. Why is he calling the self-destruct here? The programmer considered that a panic condition. _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)

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