Sins of Game Programming #2 – Code Obfuscation

One of my flaws for those that don’t know me is that I simply don’t remember everything. My brain it would appear is completely incapable of storing all the facts and information I ask it to. Over the years I have used different methods to help me remember, all with varying degrees of success.  My current system is to write everything down, I carry a black leather writing notebook with me and I take lots of notes. I use a P.D.A. for some things like contacts and mind maps but when it comes to making lists and notes, paper and pen have yet to be beaten.

One of the effects of this forgetfulness is that I couldn’t tell you the intimate details of a function I had written two weeks ago, let alone six months or a year ago without at least re-reading it and refreshing my memory. It is because of this that I consider obfuscated code a sin. This also fits nicely with working in a team of programmers where someone might have to debug and/or add new functionality to someone else’s code. The quicker it is to understand the easier it is for them to make the required modifications.

Descriptive names

Badly named variables and functions don’t help anyone. These examples I found in code that had shipped.

    int            m_MyMumIsBetterThanYours;

No it wasn’t a game about Mum’s… although I wander if there is a game there somewhere… hmmm... 

    bool           m_BumCheeks;

Enough said.

    float          m_Saving;

Is this a flag to indicate saving, in which case why a float? Or is it a percentage of save completed?

    void         * m_pAudioSample;

Not very useful, a much better way of doing this would be:

   SAudioSample  * m_pTheWarCry;

   int CCharacter::GetLife( int y )

Nothing wrong with this function… except why is there a variable passed in, and more importantly ‘y’ isn’t exactly very descriptive. Turns out this function did indeed get the amount of life and return it, while it was there it also updated the life value by applying the damage modifier to the life counter and also applied the adjustment of ‘y’. When this function wasn’t called every tick the whole life counter on the character broke!

Abusing ternary operations

Consider the following code remember that this would normally be on a single line so you would have to scroll to see the entire line.

   if (CPhysicsManager::Instance().RayCast(m_Position + (CVector::Up * METRES(2.0f)), m_Position – (CVector::Up * METRES(2.0f)), &contact_data, pActor->GetPhysicsActor() ? pActor->FindRealActor()->GetPhysicsActor() : NULL, ePhysicsShape_Static))

Would you have spotted the use of ‘?’ and ‘:’ inside the function parameter list?

Some coding standards I have worked with ban the use of ‘?’ and ‘:’ altogether mainly because it is easy to abuse and doesn’t take much to write code more nasty and tangled than the example above, however there are cases where I consider them to be fair enough and that is usually when the use is obvious. For example:

   m_Level = level_specified ? start_level  : default_level;

   result = a > b ? b : a;

English

There was a time when the length of our variable or function name would have a significant effect on the performance of the compiler. This however has not been the case for a very long time but some engineers seem to like using shorthand.

    int NmbrChars( );

vs.

   int GetNumberOfCharacters( void );

   int m_LCnt;

vs.

   int m_LifeCount;

English is my first spoken and written language I find it easier to read code that says what it is in English.

There are actually a few more items and examples under the heading of code obfuscation but this blog entry is long enough.