Navs
Code Smells Catalog
Obscured Intent

Last Revision — April 19, 2022

2 Min Read


Obscured Intent

The Obscured Intent Code Smell, initially proposed by Robert Martin in "Clean Code" [37]), is cross-smelly with other smells in the Obfuscators category. When Uncommunicative Names/Numbers are placed within a Vertically Separated Space hiding an Imperative Loop with a "What" Comment explanation on top of that, then the Obscured Intent is going to be caught quite easily by intuition or by metrics of other smells.

The code should be as expressive as possible [1]). Robert Martin gives an example of an utterly unreadable overtime function noting that even if the code is small and compact, it may still be tragic. In this case, correcting the Uncommunicative Names/Numbers would probably do the trick to make that snippet of code much more fragrant.

There is a famous real-world example of an Obscured Intent. In the Quake 3: Arena fast inverse square root, the problem is with the Uncommunicative Naming, "What" Comments, Dead Code, and Magic Numbers. I will also point out that games have a slightly different specificity for their industry. Usually, the code out there is very confusing, and priorities are not put on things such as reusability, so there is a lot to explore.

Causation

Sometimes, a developer can forget that something that seems evident to him is not as clear to other developers. There may also be cases where the developer intentionally compacts the code to appear brighter by making it more mysterious.

Problems

Comprehensibility Issues

Code does not convey meaning and thus is not understandable. It may be a considerable time waste if someone ever has to touch parts of the code that interact with an obscure intent piece of code.

Example

Smelly

An example given by Robert Martin.

def m_ot_calc() -> int:
    return i_ths_wkd * i_ths_rte \
        + round(0.5 * i_ths_rte *
        max(0, i_ths_wkd - 400))

Smelly

Quake 3 Arena Fast Inverse Square Root

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 f*ck?
        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;
}

Refactoring

  • Remove the code smells that cause Obscure Intent

Sources
  • [1], [Origin] - Robert C. Martin, "Clean Code: A Handbook of Agile Software Craftsmanship" (2008)