What Is Your Code Saying?

Developers often talk of “self describing code“. This term is a favorite answer when a developer’s poor use of comments comes into question. Often the answer: “I don’t need to write thorough comments, because my code is self describing.” Ignoring the commenting part of the example, lets dwell further on the “self describing code” claim. So my question is how well does your code reveal it’s purpose?

Let’s take the following example into consideration. Let’s say I need to determine whether data was binded to a control. The control has a property called Description, that will have a value after data was binded to it. So in order for me to determine whether the data binding operation completed successfully I could write the following code:

if ( string.IsNullOrEmpty( controlInstance.Description ) ) { … }

So what does this say about the purpose of the code? Does this line of code clearly tell you that I am actually checking whether the control was data binded? No. That knowledge is hidden away, deep inside my head. Anyone looking at this line of code will immediately be confused as to why I am doing this check. So now I am faced with two choices; I can either put a comment next to the statement, or encapsulate the logic in a property or method that will reveal the meaning of the operation (preferably we should do both). The latter option will make the code self describing, and reveal it’s intrinsic meaning:

/// <summary>
/// Checks if a data source was binded to the control.
/// </summary>
public bool DataBinded
{
get
{
return !string.IsNullOrEmpty( this.Description );
}
}

Our original line of code then becomes: if ( controlInstance.DataBinded ) { … }

Looking at this code, there is no confusion at what I was trying to achieve. We now also have one place where we define the rules that determine whether the control was data binded, so that if it needs to change, we only need to do it in one place.

The point is that there are a lot of things that need to be taken into consideration when writing and structuring source code, such as performance, coupling, inheritance hierarchy, abstraction, patterns and so forth. A very important one that I believe is too often neglected, or forgotten all together, is how well the source code communicates its meaning. In fact, personally I would say this aspect should be of the highest priority. I believe the team paying attention to this aspect of coding, will really reap the rewards once they have to start maintaining the product, especially as the original developers leave, and new ones join  the team. Considering that the maintenance of existing software can account for over 60% of all development effort, and that 70% of the cost of software is devoted to maintenance, I believe that any technique that can help with easing this task is of great importance, especially if it’s something as simple as packaging and naming your code in a clear and concise manner!

Setting up MySQL for Python (MySQLdb) on Mac OS X

MySQL is an excellent, very popular and open source database management system. A binary installation is available for Mac OS, and the process of installing MySQL on Mac OS is also very well documented. So just head over to MySQL.com, where you will find the binary installation, together with extensive installation, and usage documentation.

To connect to MySQL from Python use MySQL for Python (MySQLdb). Get MySQLdb from http://sourceforge.net/projects/mysql-python/.

1. Download MySQL from mysql.com and install the DBMS as instructed in the documentation.
2. Make sure “Library/Python/2.3” does not have:

• Directory “MySQL”
• File “_mysql.pyd”
• File “_mysql_exceptions.py”
• File “_mysql_exceptions.pyc”

Either uninstall MySQL for Python if a setup program was used to install it, otherwise manually delete them.

3. Download and unpack MySQL for Python. At the time of writing this is MySQL-python-1.2.1_p2.tar.gz .
4. Open Terminal and change to the directory where MySQLdb was unpacked to.
5. Get rid of any previous builds that might interfere, by deleting the “build” directory if it exists.
6. Edit the setup.py file, and change:
   

   return popen(“mysql_config –%s” % what)
   to
   return popen(“/usr/local/mysql/bin/mysql_config –%s” % what)

7. Cleanup any previous install attempts:
   

   python setup.py clean

8. Build MySQLdb:
   

   python setup.py build

Viola! MySQL for Python is all setup, and ready for your Python-MySQL data access code. Enjoy!