Commenting Code

[Solar]

Ah, nothing beats such literate sarcasm first thing in the morning. ;D

[Candy]

\ /
\______________________________________________________________________________________/

Allow me to place a cup onder that reply of Mystran that's so dripping with sarcasm

PS, could you give me a formula of incomprehensiveness +5 ?

[distantvoices]

That piece about Maths ... I have had quite a good laugh *rofl* because despite all the sarcasm it's so full of insight and truth.

Just for candy:

nr 1: 50!+4!/7! ->this one should give the possibility of a Hurricane in austria if a handful o dragonfly's take a **** in some pond in Sibiria.

nr 2 - my absolute fav: a?+b?=c?.

[Candy]

Just for candy:

Just for BI:

nr 1: 50!+4!/7! ->this one should give the possibility of a Hurricane in austria if a handful o dragonfly's take a **** in some pond in Sibiria.

This gives a probability of around 3.04141021326 * 10^64 + 24 / 5040, which is WAY more than 1, so it's quite more than a certainty. PS: chaos theory doesn't really work like that. You probably intended 1/$answer.

nr 2 - my absolute fav: a?+b?=c?.

how complex is that?

Anyway, this is offtopic.

[distantvoices]

just for candy:
I'm no expert in formulas in chaos theory. The possibility calc's are something I've learned at some needed math's class, so I've set off and made a jest around that. *gg*

The phytagoras formula isn't anything complex, to be honest, but to some individuals, even this one is a complete mysterium.

BTW: some offtopic distraction isn't sooo bad after all, is it?

BTW II: to contribute to the topic:

A well measured amount of comments is always good. One need not comment every whim in the functions, but to describe what a function is expected to do isn't a bad thing. also examples of usage are nifty.

[Solar]

Also examples of usage are nifty.

Now there's a can of worms. Something that drives me mad in my everyday work: Sure the class and all it's functions are cleanly documented in the class' header file.

But there's no description of how you're supposed to use that thingy.

That can become a real nuisance in versatile utility classes like e.g. "Date". A quick example of how to construct a Date object from an ISO date (20050607), how to convert to and from Julian calendar, how to add and substract days / months / years, how to get the ISO date from the object again.

No, I have to sift through the carefully alpha-sorted constructors and member functions and do some trial-and-error...

Keep the person in mind that will have to work with your code later on. Leave every piece of code in the state in which you would wish to find it, or a bit better than it was before - whatever is better.

[ark]

Heh, the mathematics discussion isn't completely off-topic...after all, mathematical formulas are a perfect example of why we don't tolerate variable names that are not self-documenting in programming. Mathematicians use variable names that are easy to write...while we require names that are easy to understand.

[TheUnbelieverNotLoggedIn]

I tend to describe the basic intention of a procedure (or block of code, if there is a large lot in one procedure) at the start, followed by a pseudocode version. I then comment any especially important lines individually - using whitespace to separate them from the rest of the code.

[Pype.Clicker]

Also examples of usage are nifty.

But there's no description of how you're supposed to use that thingy.

That can become a real nuisance in versatile utility classes like e.g. "Date". A quick example of how to construct a Date object from an ISO date (20050607), how to convert to and from Julian calendar, how to add and substract days / months / years, how to get the ISO date from the object again.

seconding that. I've been highly impressed by how documentation of CPAN (perl archive network) is maintained and how easy you can reuse those modules from the simple fact that you have sample code of what you're doing.

Btw, this is probably more a problem of _documenting_ your library than actually commenting.