Refactoring explained to an absolute beginner

June 26, 2010 – 6:46 pm Tags: ,

Recently while on a drive with a non-programmer friend, I talked with him about code complexity and manageability, how very complicated code is detrimental to productivity and stuff like that.

Later on, I decided to explain it to him with actual code examples, although the most he has ever done was some HTML back in elementary school.

Here’s what I told him…

A simple example with HTML, PHP and SQL

I used HTML, PHP and SQL to create a very simple example: A simple webpage which displays a list of things loaded from a database.

The reason I chose these three is because they allowed me to present a very simple example, but still would allow me to create a scenario where it would be easy to show how code can become complex, and how you would change it to improve.

Stage 1: HTML/PHP/SQL-soup

The first stage is the most straightforward way you could do this:

<html>
 <head>
  <title>Listing</title>
 </head>
 <body>
  <h1>List</h1>
  <?php
  $db = mysql_connect('localhost', 'username', 'password');
  mysql_select_db('database', $db);
 
  $sql = 'SELECT * FROM lista ORDER BY id DESC';
  $result = mysql_query($sql, $db);
  ?>
  <ul>
    <?php
    while($row = mysql_fetch_assoc($result)) {
      echo '<li>' . $row['name'] . '</li>';
    }
    ?>
  </ul>  
 </body>
</html>
<?php
mysql_close($db);
?>

So in this example, we have a page that is very typical for a PHP beginner: It mixes everything together in one file.

Stage 2: Split output and data processing

To improve from stage 1, we can split the processing of data and output. We do this to achieve separation of concerns.

This time, we have two files: index.php and a template file index.phtml

index.php

<?php
$db = mysql_connect('localhost', 'username', 'password');
mysql_select_db('database', $db);
 
$sql = 'SELECT * FROM lista ORDER BY id DESC';
$result = mysql_query($sql, $db);
 
$list = array();
while($row = mysql_fetch_assoc($result)) {
  $list[] = $row;
}
 
mysql_close($db);
 
require 'index.phtml';

index.phtml

<html>
 <head>
  <title>Listing</title>
 </head>
 <body>
  <h1>List</h1>
  <ul>
   <?php foreach($list as $item): ?>
    <li><?= $item['name']; ?></li>
   <?php endforeach; ?>
  </ul>  
 </body>
</html>

As you can see, now our data processing code is in index.php and the HTML markup is in the index.phtml template file. It’s now much more clear what the structure of our HTML markup is (and we could now reuse it etc.)

Stage 3: Reusable functions

We can still perform some improvements to the code. Let’s extract the data processing code into separate functions. By doing this, we will improve the readability of the index.php file and if needed, we could easily reuse the data processing code.

We will create a new file, called database.php, which will include our functions:

database.php

<?php
function connect_db($user, $pass, $host, $dbname) {
  $db = mysql_connect($user, $pass, $host);
  mysql_select_db($dbname, $db);
  return $db;
}
 
function get_list($db) {
  $sql = 'SELECT * FROM lista ORDER BY id DESC';
  $result = mysql_query($sql, $db);
 
  $list = array();
  while($row = mysql_fetch_assoc($result)) {
    $list[] = $row;
  }
 
  return $list;
}

We will also change index.php to reflect the extraction of the code:

index.php

<?php
require 'database.php';
 
$db = connect_db('user', 'pass', 'address', 'database');
$list = get_list($db);
 
require 'index.phtml';

As you can now see, the code is much easier to understand as we can clearly see from the function naming what it does and the index.php file is also much shorter.

Conclusion

By splitting code into their separate places, you can easily improve your code. You don’t need to be a rocket scientist to understand the basic points.

I did omit some things here, though: in reality I did give a brief introduction of HTML, PHP and SQL to my friend, and gave him an example of how the resulting page would look and stuff like that. Oh, we used Google Wave for it, and it worked pretty well, so maybe it isn’t as useless as it sometimes seems :D

Share this:

RSS feed Subscribe to my RSS feed

About the author

Jani is a 15 year veteran of the software industry. He's currently available for consulting

  1. 11 Responses to “Refactoring explained to an absolute beginner”

  2. That’s a nice plain and simple way to explain refactoring.

    A little detail: on the last index.php you have require ‘tietokanta.php’ which I believe is finnish for ‘database.php’ ;)

    By Rogério Vicente on Jun 26, 2010

  3. Suggestion: Don’t use short tags. =)

    By EllisGL on Jun 27, 2010

  4. Thanks for spotting that Rogério – you are correct, it indeed is finnish for database :) Fixed.

    By Jani Hartikainen on Jun 27, 2010

  5. Hm, the php-template-Syntax with short tags is turned off by default in 5.3 and will soon completely fall out of php so what will happen is that you have to use even uglier code within your php-template-files :(

    By David Müller on Jun 28, 2010

  6. Great story. Explaining complex to a newbie is a really helpful exercise, because you need to articulate all the things that you take for granted. For example, the fact that in Step 3, $list is available, and in the same scope in both files. How a dev explains their code is a really great indication of what kind of coder they are.

    http://chr.ishenry.com/2009/07/01/explain-your-code/

    By Chris Henry on Jul 14, 2010

  7. “Recently while on a drive with a non-programmer friend, I talked with him about code…..”

    Wow. Nice friends you have there. My non programming friends would listen to about 1 sentence of that before saying “shut up with the work/tech talk, let’s talk about interesting things” And honestly, they would be 100% right.

    Are you sure your non-programmer friend– who was trapped in the car with you– actually cared to listen to the topic of “code refactoring”???

    Ive been trapped in cars/conversations with geek programmers who tried to yap on and on about code stuff no one cared about. It was the last time we included him in ANY social activities.

    If he’s still fiends with you, you’re a lucky man.

    ;o)~

    By Dave M on Aug 22, 2010

  8. Dave, ha, I have that sort of friends too, who get a headache from technical stuff ;)

    This one is sort of a techy/nerdy guy though. He just isn’t a programmer.

    By Jani Hartikainen on Aug 22, 2010

  9. lol. That guy we were trapped in the car with was actually my boss…

    …so I do listen to him ‘yap on and on’ at work— just not in the car on the way to a Yankees baseball game.

    ;o)~

    By Dave M on Aug 22, 2010

  10. P.S. — great website, btw. Lots of useful hints and tips here.

    Tnx for sharing.

    By Dave M on Aug 22, 2010

  1. 2 Trackback(s)

  2. Jul 3, 2010: Max’ Lesestoff zum Wochenende – 26/2010 | PHP hates me - Der PHP Blog
  3. Aug 4, 2010: Source code refactoring at Appunti di viaggio

Post a Comment

You can use some HTML (a, em, strong, etc.). If you want to post code, use <pre lang="PHP">code here</pre> (you can replace PHP with the language you are posting)