Greenie sentences

Weiye Chen

Is there a mentality among programmers that writing "greenie sentences"(a.k.a Comments) in codes are only for amateurs? It seems like i am the only one making my code as "green" as possible. It feel frustrating trying to understand other person's code that are long and "un-greened". X| Weiye Chen Life is hard, yet we are made of flesh...

Eytukan

OMG!, Nope , certainly not(at least for me). I love to see long code without *greens* . that sometimes says its a "Finished product". Instead of putting these greens inside the code, its better to make a separate document exlpaining each block of code. I have some samples like that. I love to read the code document first, then have a look at the actual code. Too much of comments in in the code certainly distracts my eyes X| .

--[V]--

[My Current Status]

shreekar

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. Shreekar http://shreekarishere.blogspot.com

R Giskard Reventlov

Weiye Chen wrote:

Is there a mentality among programmers that writing "greenie sentences"(a.k.a Comments) in codes are only for amateurs?

I would hope not! We comment (in a standardised way) everything and then use NDocs to produce .chm files. If anyone tries to sneak code in without reasonably verbose commentary it gets picked up and rejected. If you can't explain what you've done then you probably dodn't understand it. Have always done so and most of the coders I've worked with have always done so as a matter of course. It is sloppy not to. Anyway, that was my tuppence worth. home
bookmarks You can ignore relatives but the neighbours live next door

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