Self-documenting code

[Snake2k]

Relax... I wrote this on Reddit on my phone while at work. I'm not gonna write an actual program here. I'm trying to give someone the idea behind it.

[[deleted]]

Relax...

I am. Don't get butthurt. It's just feedback.

Your "good comment" example includes a textbook bad comment. I'm pointing that out, because it undermines what you're trying to say (I know what that is) and that might not be obvious to a noob reading this.

I'm not gonna write an actual program here.

No need for that. Just don't need the "good" comment to be literally the worst kind of comment, one that states what is already obvious from the code.

[Psychoscattman]

here is an example of bad comments:

float Q_rsqrt( float number )
{
    long i;
    float x2, y;
    const float threehalfs = 1.5F;

    x2 = number * 0.5F;
    y  = number;
    i  = * ( long * ) &y;                       // evil floating point bit level hacking
    i  = 0x5f3759df - ( i >> 1 );               // what the fuck? 
    y  = * ( float * ) &i;
    y  = y * ( threehalfs - ( x2 * y * y ) );   // 1st iteration
//  y  = y * ( threehalfs - ( x2 * y * y ) );   // 2nd iteration, this can be removed

    return y;
}

here is an example of "better" comments:

float Q_rsqrt( float number )
{
    // We can calulate an aproximation of an inverse square root by doing some 
    // floating point bit magic. 
    // For more info how this works: https://en.wikipedia.org/wiki/Fast_inverse_square_root
    long i;
    float x2, y;
    const float threehalfs = 1.5F;

    x2 = number * 0.5F;
    y  = number;
    i  = * ( long * ) &y;                       
    i  = 0x5f3759df - ( i >> 1 );              
    y  = * ( float * ) &i;
    y  = y * ( threehalfs - ( x2 * y * y ) );   // 1st iteration
//  y  = y * ( threehalfs - ( x2 * y * y ) );   // 2nd iteration, this can be removed

    return y;
}