One of the conventions I use is expanding out algorithms--doing it "long hand". This is writing each step of the equation on a new line so the process can be followed step-by-step. It takes more lines of code, but makes for a good deal more readability--the results are the same. Lets take, for instance, the Quadratic equation:
The following implementations solve for the first term of the equation:
float QuadraticEquationLong( float a , float b , float c )
{
float Accumulator;
Accumulator = b * b;
Accumulator -= 4 * a * c;
Accumulator = sqrt( Accumulator );
Accumulator += -b;
Accumulator /= 2 * a;
return Accumulator;
}
float QuadraticEquationShort( float a , float b , float c )
{
return ( -b + sqrt( b * b - 4 * a * c ) ) / 2 * a;
}
Both do exactly the same thing, but the difference is, the long hand version preforms the function in a clear step-by-step manner. For the quadratic equation, one could argue the short version is still quite readable. But here is a real-life example of why I choice to do things long-hand:
BitMask = (uint16)( 1U << min( ValueA , ValueB ) ) - 1 );
What is going on here is this: A bit mask is being created for some number of bits. The number of bits is the smaller of ValueA and ValueB. But a mistake had been made during implementation. The original line actually read:
BitMask = (uint16)( 1U << min( ValueA , ValueB ) - 1 ) );
The collection of parentheses distracted the coder and the -1 had been placed in the wrong location. The above will not create the desired results. Now the expanded version:
mask = min( ValueA , ValueB );
mask = 1U << mask;
mask -= 1;
Now the expand version with the error:
mask = min( ValueA , ValueB );
mask -= 1;
mask = 1U << mask;
Simply reading the code line by line makes the mistake obvious: Find the smallest value of ValueA and ValueB; subtract 1, shift 1 to left this many bits.
The downfall of this method is the possibility of not producing the most efficient code. If speed is an issue, take the time to work out the problem to see what's best for order of operation. Or, if you're working with a good compiler, do it short hand, look at how the assembler broke it down and work it backward. Or if you need it as fast as possible, implement the function in assembly.
For most instances, I'd recommend long-hand. It is going to make things clear, and that's can save some hair-pulling in the future.
