Tip: use clearly readable variable names, and constants!

Yes, you know what code you write and you also know how it works. You can find your way around it. But what if you haven't touched a piece of code for months or even years. Or what if someone else needs to work with your code. Prevent a hell: use clearly readable variable names and constants.

As an example, let's take a look at an if-statement that I encountered in FUD forum. Note that I have very little experience with FUD forum, and even less with their code:

if ($obj->avatar_loc && $a & 8388608 && $b & 8192 && $o1 & 28 && !($c & 2))

Now, that first object attribute I can figure out, that is not a problem. But now, let's have a look at what else is happening here. Actually, what the hell is happening here? $a, $b, $c and $o1 are absolutely not clear to me, and neither is the use of 8388608, 8192, 28 and 2.

Now, variables should never be long because that will clutter the code, but they should be clearly readable and understable, think: $user_id (or $userId depending on your preference), $file_to_update, $my_own_variable.

Same for "magic" values. I usually have an abstract class named Constants or something similar in which I "save" these magic values, so that the code becomes more clear. As an example, in my code I would use Constants: EBUG_ENABLED or Constants::IS_ADMIN.

That makes the code so much more clear and understandable. Because if you haven't worked on code for ages and you need to change or add something, or someone else needs to work on your code, you want that to be equally nice as writing the code in the first place. And everybody knows how annoying maintainance work is as opposed to developing a brand new project with lots of fresh code and fresh problems to solve.

And especially when you release your code as Open Source software, it's even more important. Because you know people will be looking at it and might want to change it. It's not just important that it works properly, but also that people will be able to easily find their way around your code. Without that, there will not be that much developers willing to join your community.

I had to learn this lesson a few years back now, and I am so happy about this. Because every once in a while I need to look at very old code I wrote, and usually it does not make things easy that I used the alphabet for my variable naming.