Documentation

Code

    float y = number;
    long i = *(long*) &y;
    i = 0x5f3759df - ( i >> 1 );
    y = *(float*) &i;
    y = y * ( 1.5F - ( ( number * 0.5F ) * y * y ) );

 

float reciprocal_sqrt( float number ) {
    float y = number;
    long i = *(long*) &y;
    i = 0x5f3759df - ( i >> 1 );
    y = *(float*) &i;
    y = y * ( 1.5F - ( ( number * 0.5F ) * y * y ) );
    return y;
}

1. It's too complex to understand, it must be

important

2. It's too complex to understand, it must be

replaced

#include <cmath>
float reciprocal_sqrt( float number ) {
    return 1 / sqrt( number );
}

 
float reciprocal_sqrt( float number ) {
    float y = number;
    long i = *(long*) &y;
    i = 0x5f3759df - ( i >> 1 );
    y = *(float*) &i;
    y = y * ( 1.5F - ( ( number * 0.5F ) * y * y ) );
    return y;
}

#include <cmath>
float reciprocal_sqrt( float number ) {
    return 1 / sqrt( number );
}

Documentation

/**
 * Calculate the reciprocal square root.
 * @param number The input number
 * @return The reciprocal square root of the input
 */
float reciprocal_square_root( float number ) { ... }

/**
 * Calculate the reciprocal square root.
 * @param number The input number
 * @return The reciprocal square root of the input
 */
float reciprocal_square_root( float number ) { ... }

/**
 * Calculate the reciprocal square root.
 * @param number The input number
 * @return The reciprocal square root of the input
 */
float reciprocal_square_root( float number ) { ... }

Self-documenting Code

Good Documentation

1. What does the function do?

2. What are the inputs?

3. Why does this function exist?

4. How do I use the function?

/**
 * Quickly calculate the reciprocal of the square root of
 * the given number. This is used instead of the
 * standard sqrt function for performance. Used by
 * [the vector2 class] to calculate magnitudes and unit
 * vectors.
 *
 *   // Calculate the normalized vector of an input vector
 *   vector2 input( 5, 6 );
 *   double len = pow(input.x, 2.0) + pow(input.y, 2.0);
 *   double mag = rsqrt( len );
 *   vector2 normalized( input.x * mag, input.y * mag );
 *
 * See https://en.wikipedia.org/wiki/Fast_inverse_square_root
 */
float reciprocal_square_root( float number ) { ... }

Great Documentation

More Than What

More Than How

Why

Teaches

Concepts

Teaches

Business Rules

Teaches

Domain Model

When to Use

Something Else

Remembers

Write Good

Documentation

Modules

Description

Examples

Cross-References

Functions

Description

Examples

Cross-References