Explaining and justifying your decisions

At the most very basic level, take this bit of code for example:

ksort($files);

To most PHP developers it is obvious that this bit of code sorts the $files array in key order. But it is not obvious to any PHP developer *why* I have done this. Adding a comment to say what I am doing and why would help speed up the recognition of what this code does; but more importantly, explain why this code is here.:


/**
* Sort the $files array in Key order. We want them displayed on the
* page in added order, and the $files array is not necessarily
* sorted in that order before this stage.
*/
ksort($files);


Using code comments as a tool: Autocompletion

There are other areas of an application where documentation can be even more useful. Modern Code Editors and IDEs will read what are called ‘docblocks‘ at the top of class, method or function definitions and add the information in the docblock in to your autocomplete prompts. So how do these docblocks work?

Docblocks are generally in this format (opened by /**, closed by */, with a * at the start of every line inbetween) and always apply to the next uncommented line of code. In this case, the line of code beginning with $page_posted_to = is documented by the docblock above.:


/**
* Determine if the page has been posted to with an action.
*/
$page_posted_to = (array_key_exists('action', $_POST) && !empty($_POST['action']));


Within docblocks you can contain ‘tags’. These ‘tags’ begin with an @ symbol and are often read or interpreted by documentation generation utilities or IDEs/Editors for autocompletion. A comprehensive list can be found on the Wikipedia page for Docblocks. Using these tags can encourage you to include information in your documentation that you might forget to include normally, ie the expected data type of function parameters.

At it’s most basic use, docblocks usually look something like this when describing a function or method:


/**
* This function adds two values together
* @param int $a The first value
* @param int $b The second value
* @return int The value of $a + $b
*/
function add_together($a, $b) {
return $a + $b;
}


As you can see, including these docblocks explains in plain english what the function does, what parameters it expects, and what it will return. This can save the next developer that reads your code tonnes of time and headaches, but most importantly of all, will make your code editor or IDE (if it supports autocompletion and docblock parsing) much more intelligent when it comes to helping you call your own methods or functions.

The idea of the ‘architect’ of this system was that any interaction with databases or storage of data; ie the models; would be shared in the central library.  This would mean that changes such as the one I worked on with is_deleted = 1 would be simple and made in one place, and one place only.  A true implementation of the ‘Don’t Repeat Yourself (DRY)’ principle.

The nature of this platform is that it is exactly that. A platform.  This typically means that no two implementations of the platform are identical, so to speak.  The platform is built upon and ‘extended’ to do what the individual customers want from their online shop.  This sometimes means that custom product ‘getter’ blocks of code are written.  Often, the ‘quick and easy’ approach had been taken with these , and they had simply been added as standalone functions in the individual project’s library, called things such as getAllProductsFlaggedAsSpecial()  This obviously meant that when I implemented my is_deleted changes in the central library, and wasn’t aware of the custom nature of these custom product selectors, the sites that used those custom product selectors continued to display deleted products.  Big oops!

This now means that I will need to go through the individual implementations of the platform, search for any custom product SQL that is being built, and add the AND p.is_deleted = 0 in to them.

This whole problem got my thinking about how I would approach this issue (The need to build custom product getter functions in individual implementations of the platform), and here’s how I think I’d do it.

I think I would ensure that all custom product getter functions were in fact methods in an extension of the main Model class that then called a buildWhereClause method that added any global product SQL (eg AND is_deleted = 0) in, like this:


class Model_Product extends Base_Model {
...
function buildWhereClause($sql) {
return 'WHERE p.is_deleted = 0 AND '.$sql;
}
...
}



class MyShopNameModel_Product extends Model_Product {
function getProductsFlaggedAsSpecial() {
...
$sql = "SELECT * FROM product ".$this->buildWhereClause('is_special = 1');
...
}
}

Essentially, what I learnt here was that the developer to begin with that wrote these ‘quick functions’ saved his or herself half an hour or so, but cost me (2-3 years later) a fair amount of time in debugging.  I think this is evidence that coding things the quick way and implementing a fast solution is often a false economy, and someone later in the life of the software will have to spend the time saved (and possibly more) to work around the disadvantages of the quick approach.

My reasons for this decision are as follows:

1. Database collation.  Searching for strings LIKE '%Ed, Ed & Eddie%' starts to get complicated if you have converted & to & – you have to remember to convert entities in your search string as well.  This could also potentially mess up the effect ORDER BY clauses in the SQL queries you write have on the dataset.
2. Data Integrity.  If in the future I decide that I all HTML, or just specific previously blacklisted HTML tags to be allowed, the data is all still complete and certain aspects of the data have not been removed.
3. Application Consistency.  I know that if I am ever displaying data selected from the database it will need to be ‘sanitised’ before being displayed to the user either in repopulated ‘edit’ forms or in a normal ‘view’ type screen.

I also did a little bit of research in the cakephp manual (as we will be using cakephp for this next project) to see what cakephp creators thought about this and it seems they reached the same conclusion (quoted from this page):

For sanitization against XSS its generally better to save raw HTML in database without modification and sanitize at the time of output/display.

They don’t give any specific reasons but I imagine that their thought process was similar to mine.