Greenie sentences

[Weiye Chen]

Ah, why is this voted down? :confused: [edit] A programming question? [/edit] Weiye Chen Life is hard, yet we are made of flesh... -- modified at 5:50 Tuesday 30th May, 2006

[Weiye Chen]

shreekar wrote:

I prefer the middle path - short description of the function/procedure at the top with desdription of parameters and then add comments inline ONLY IF (a)the code implements some weird business logic OR (b) is convulated to understand by a first time reader.

Yes, i like that style too. Weiye Chen Life is hard, yet we are made of flesh...

[Super Lloyd]

Weiye Chen wrote:

Ah, why is this voted down?

Do not fear! Some random readers randomly tag with 1 73% of the posts. Means nothing....

[Graham Shanks]

We have two levels of greenies: Our library header files are heavily documented (ratio of comment lines to code lines often exceeds 10 to 1). This documentation is used to generate the library manuals (we use doxygen), so needs to be sufficient for an intelligent programmer to be able to understand what the function does and how to use it. Source files (i.e. .c & .cpp) are documented more sparingly. Long functions will be split up with comments telling roughly what (at a high level) the code block does. Tricky bits of code or places where we've had to change code to work around obscure bugs tend to get commented much more heavily (so that it doesn't get changed back). Comments in source code (not header files) should say why the code is structured the way it is. I expect that engineers can understand the syntax of the code without further explanation. In code reviews I automatically fail code if it contains comments such as: // Increment i; i++; Graham -- modified at 7:09 Tuesday 30th May, 2006

[Marc Clifton]

I changed the comment color to red (maroon). The more the code bleeds, the better! Marc Pensieve Some people believe what the bible says. Literally. At least [with Wikipedia] you have the chance to correct the wiki -- Jörgen Sigvardsson

[Roger Stoltz]

Marc Clifton wrote:

The more the code bleeds, the better!

Soon on a screen near you: Scary Code 00000010

---

_It's supposed to be hard, otherwise anybody could do it!

Regarding CodeProject: "resistance is pointless; you will be assimilated"_

[leppie]

**

How xacc.ide transforms text to colored words on the screen
Intel PentuimM (aka Centrino) undervolting

**

[Tarakeshwar Reddy]

Weiye Chen wrote:

that writing "greenie sentences"(a.k.a Comments) in codes are only for amateurs? It

Most of my code is like un-greened. After I am done with the project or a screen, I add comments for the functions and a comment here and there for some logic which may not be understandable for a 3rd person. But I just hate it when people make the whole screen green by adding comments to every single line(some cases you may need, but not all).

---

Tarakeshwar MCP, CCIE Q(R&S) Before you criticize someone, you should walk a mile in their shoes. That way, when you criticize them, you're a mile away and you have their shoes. !sgub evah t'nseod margorP sihT ?sgub naem ayaddahW

[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