ICode , BangladeshPower and Confidence in code

Please read my previous article Naming Convention Part 2: Purpose of a Variable before reading this one.

Here goes two ugliest variable names which are most widely used, especially in Database applications: row and results with aliases like rows, res, result, etc. We do it to code very fast.

This type of generic names can cause logical errors that you might never find. Just saw a code written by another developer in PHP which I am currently testing:

$res1 = mysql_query(“select * from category ……………….);

while($row = mysql_fetch_assoc($res1))

{
……..100 lines of code

for($j=0;$j<count($a2[1]);$j++)

{
$cat_id = $row['cat_id'];

…….lines of code

$result = mysql_query(“select prod…..”);
if(mysql_num_rows($result) > 0)

{
$row = mysql_fetch_assoc($result);

………………….lines of codes

} //if ends

……..lines of codes

} //for ends

……..lines of codes

} //while ends

So the code breaks now and then. And as the second use of $row is in a conditional code block, it may break  a long time after delivery of the code. Because initial tests may pass and which actually occurred in this solution. So naming convention is a necessity in software engineering not an option. These commonly mistaken names cause you to make mistakes!

First part:

What is a variable actually? Simply it’s a container that has a name. The best practice creating and using variable is to stick a name to a single purpose only.
Say we have some chemicals stored in some bottles and we put a tag on each bottle with the name of the chemical it contains. Now if a chemical is used up, a bottle gets free; will you use it for a different chemical without changing the tag? Think what might happen in that case, you will need to remember when you used that bottle for what and the tag fails to help you. So what is the purpose of the name tag if it doesn’t help you to know what the bottle contains?

When you are going to build a wel-managed software, you should not use the same name for different purposes. If the purpose of a variable is a single thing, then you can easily tell what type of data you saved in it a million lines ago in your code. Here is a dirty example in PHP:

$results=GetCustomers(); //returns an array of customers

…
…a million lines
…//$result variable is freed.
…
$results=GetProducts(); //returns an array of products
…
…a million lines
…two million lines
…
foreach($results as …)
….
…

Now look at the ‘foreach’ block! You need to improve your code after 1 year, and you came across the ‘foreach’. You cannot tell immediately what is in $results: products or customers?

But if you had used two variables called ‘$allCustomers’ and ‘$allProducts’, there would be no confusion in your code. They would serve for a single purpose each.

Second Part:

Now a purpose should have a single variable only. Like a chemical may have two names in different disciplines. If you have two bottles containing the chemical and tag them differently, it will make you slower than if they had the same tag as long as the chemicals are the same. In software engineering, the problem goes bigger.

If you have an array of customers, don’t use different names in different places for them (if not needed). Like in a function you used ‘$allCustomers’, in another ‘$customers’, another ‘$onlyCustomers’. This lowers readabilty, for others, and for YOU!

Overall:

1. All the variable names are in camel notation (aName, totalAmount).

2. All the attribute names are in camel notation. That goes for forms, entity atrribute names, entity names. Say you have a entity called ‘person’ and it has some attributes, then we choose the attribute names this way – name, dateOfBirth, currentAddress. If we need a table for a relation between a person and a terrorist, we can name the relation like ‘personTerrorist‘ or ‘terroristPerson‘

3. Classes and Functions are in dot net notation (GetResults(), Client, Order, Print())

4. Everything must be built with OOP structure. Except for some occasional PHP works. When making a module for a already built system in PHP, then it must be made in OOP. There are no global variables/constants in OOP world. If you need those, you can make a abstract class with static members that meets the requirement. Exception is for very high performance software for which actually all the rules can be broken :p

5. All the classe names must have a prefix which is decided per project. Like if we are making a Game called Alex’s Treasure, we would choose a prefix ‘Alex’ before starting the project. So if we need a class called ‘Island’, we will have to use the name ‘AlexIsland‘ as the class name.

5. All the static and global variables are in capital letters with words separated by underscore. like ROOT_DIRECTORY, OBJECTS_CREATED

6. All the constants are written like no.5 with two underscores added to the ends. like _PI_, _MAX_LENGTH_

7. All the functions are actions. So name should sound like ‘do something’ or ‘something happened’. Order of the words cannot be different from how it should be told. Like you are working on some operations related to customers and banks. These names are ugly

CustomerBank(), CustomerAddress(), CustomerStatus(), CustomersMostImportant(),

problems with those names are

1. they doesn’t sound like having an action
2. the words’ order is not the way you say
3. the seem to stick the customer at the beginning of the name!

So we replace them with this : GetCustomerBanksDetails(), GetCustomerAddress(), GetCustomerStatus(), GetMostImportantCustomers()

Database related:

1. Entity names must be in singular number. So ‘employees’ is not a valid entity name, ‘employee’ is the correct one.

2. Relation table names also in singular number.

3. after executing every query, you must at first check the error. In mysql and PHP, use ‘mysql_error()’ function. Don’t rely on other avaiable functions to determine the errors.

4. I don’t know how mysql_insert_id() handles race conditions. So, if you don’t know the internal code architecture of mysql, never use it without table locking (even if mysql developers use it without table locking). You need to lock all the tables that you use in a script for mysql if you need to lock at least 1 table. That’s a mysql weakness only.

PHP related:

1. Turn on all the error, notices, warnings from php.ini file for development and testing. You must eleminate every single notice/warning. (that relates to the logical errors)

2. Don’t rely on empty() function of php. search google for ‘why’. You must read very very carefully php’s function definitions and experiment with them. What you assume may not be what it actually is.

3. Do you know abour magic quotes?

Goals of naming convention:

1. Readability,

2. Manageability,

3. Reusability,

4. Perfect Prediction