Sunday, September 6, 2009

Names in our code

This is just a summary of some rule-of-thumbs when developing source codes.

When coding, do these :
  • use descriptive names
  • please classify/categorize so we have shorter source files. Or, we have fewer source files in each folder (distribute files into category folders). In OOP, we should refactor into new classes if things gotten too crowded in one class, or even refactor the class into different packages. In PHP, we should refactor into new files and/or new folders.

Rules that were Anti-patterns :
  • don't use generic names like $query. When reading it, I don't have a clue what does it stands for, a query to the users table, or a query to delete a user, or what? OK, maybe it can be used if the scope is local, that is, I could easily look for the meaning in the same function or small file.
  • avoid long parameter list. It is difficult to find out which parameter means what. We could use: a value class in OOP languages, or associative array in PHP, or even object in PHP, to give meaningful parameter. When function insert(name,address,groupid,status,isAdmin) being called, it becames insert($name,$address,null,0,$isAdmin), and we must look elsewhere what does the 0 stand for. If we have $entity = array('name' => $name, 'address' => $address, 'groupid' => 0, 'isAdmin' => isAdmin); and call insert($entity); things are much easier to understand and easier to modify.

No comments: