).
Because each function signature is so well commented and functions are usually very short, there is little need for comments in the body of each function unless they do something tricky.Code: Select all
// sin, except basic period is [-0.5, 0.5]
double Msin (double x) const {
x -= rint(x);
x *= 2 * M_PI;
// this is basic 7th order Maclaurin for sin(x)
// and it's quite accurate at [-Pi/2, Pi/2]
// and more or less decent at about [-Pi, Pi]
//
double x2 = x*x;
return x*(1+x2*(-1+x2*(1-x2*(1.0/42))*(1.0/20))*(1.0/6));
}
Code: Select all
// some bogus value, any bogus value will do.. just bogus enough ;)
height.last_x = height.last_y
= light.last_x = light.last_y
= blend.last_x = blend.last_y = 0xDEADBEEF;
Code: Select all
// If XMODIFIERS is not set, we probably want to
// use X Servers internal translation instead of
// "none" which would default.
if(getenv("XMODIFIERS"))
XSetLocaleModifiers(""); // failure is non-fatal..
else XSetLocaleModifiers("@im=");
Code: Select all
// These two friends manipulate the "parent" attribute.
// They would be Container's members if that wouldn't cause
// unfortunate cyclic definitions.
friend void Container_add(Container *, Component *);
friend void Container_remove(Container *, Component *);
Code: Select all
// seems to be needed on x86, probably endian dependant..
png_set_bgr(png);
Code: Select all
return 0; /* should not be reached !! */
Code: Select all
/* NOTE: this is important information that you absolutely
* must read before you attemp to decipher my code.
*/
If your code couldn't be read without comments, you're in deep trouble (or coding Perl, APL, Brainfuck, or LISP).Joel wrote: In general, well-structured code with short functions and descriptive variable names (specifically not over-abbreviated ones) can be read without them.
98% ACK.You absolutely should comment functions/methods and classes to give an overview of how they are used...functions in particular need comments to tell their pre- and postconditions, return values, etc. No one should have to look at the code for your function to use it, only to modify it.
Yep. But sometimes a single statement can be sufficiently complex to warrant a comment. Perl regexp's, for example.In general, any time you have a group of statements that are working toward a particular goal but it takes more than a few statements to get there, you should comment the overall goal and leave the code to specify the details, with the one exceptional case being if the details are particularly tricky.
A catching maxim is, "comment now because later never comes".I tend to write code first and then comment later, which I'll readily admit isn't all that great a habit.
I was using the word "read" in the sense of both picking out the syntactic structure and understanding what the code is doingBut to modify your code, you have not only to read it, but understand it. If a piece of formula munching is intended to to a Newton approximation, why not add a note that it's a Newton approximation to the loop? It makes reading so much faster, and just in case your code doesn't do it right, the maintenance coder might have an idea what it should do (a Newton approximation) - instead of looking at a piece of maths that might or might not do what it's intended to do.
Yeah, it's not a rigid rule. Most of the things I was saying were more general guidelines. I've never programmed in Perl, so I don't know the details of what it requires, but in C, C++, or Java programming, I would tend to say that if a statement is complex enough to need to be commented, then it should be more than one statement, anyway. I'm sure there are exceptions to this (meaning that there are times when this would actually hinder readability instead of helping it), but I would say in general complex statements are the less readable alternative.Yep. But sometimes a single statement can be sufficiently complex to warrant a comment. Perl regexp's, for example.
Perl, APL or Brainfuck.Solar wrote: If your code couldn't be read without comments, you're in deep trouble (or coding Perl, APL, Brainfuck, or LISP).
I can see that you have never visited a mathematics class (of any level from elementary to undergraduate at least), because otherwise you'd know that the best way to teach mathematics is to show someone several mystical formulas of incomprehensiveness +5, and assuming that by looking at them long enough one suddenly learns something about mathematics.98% ACK.
But to modify your code, you have not only to read it, but understand it. If a piece of formula munching is intended to to a Newton approximation, why not add a note that it's a Newton approximation to the loop? It makes reading so much faster, and just in case your code doesn't do it right, the maintenance coder might have an idea what it should do (a Newton approximation) - instead of looking at a piece of maths that might or might not do what it's intended to do.
I always though the regex were the only readable part in Perl.Yep. But sometimes a single statement can be sufficiently complex to warrant a comment. Perl regexp's, for example.
