The document provides development notes and best practices for writing transparent, readable code. It recommends: 1) Making code obvious through comments and layers of abstraction while balancing complexity. 2) Prioritizing searchability and readability over performance within reason. 3) Avoiding clever code that can become brittle, and keeping abstraction and variable names consistent to improve readability and changeability. 4) Keeping data formats pure and refactoring accessor functions, not data formats, when possible. 5) Embracing micro-MVC patterns with separate model, controller and view layers.

1. Development Notes
Alex King

2. Transparency FTW
• Code should be obvious
(comments help, but are supplemental)
• Abstraction worth layers of complexity
(it’s got to be
adds
it, frameworks vs. one-
offs)
• Searchability is important
• Readability > most of the time)
(within reason,
Performance

3. Example
class Example {
static $meta_prefix = ‘_foo_’;
NO! [...]
function bar() {
update_post_meta($post_id, self::$meta_prefix.‘my_key’, 1);
}
}
class Example {
YES [...]
function bar() {
update_post_meta($post_id, ‘_foo_my_key’, 1);
}
}

4. Refactoring is
Development
• Clever = brittle
• Avoid too many levels of abstraction
• Shallow code is more readable/
changable
• Consistent variable names
foreach ($objects as $object) {...

5. Data Formats / APIs
• Keep data as “pure” as possible
• Can always refactor what the
accessor functions do, but don’t
change the formats (if at all possible)
• JSON encode vs. serialize for
serialized data (allows for SQL find/

6. Example
// hard-coded // database backed
function foo() { function foo() {
return array( global $wpdb;
‘bar’,
‘baz’, // some stuff happens here
);
} return $wpdb->get_col(“
SELECT [...]
”);
// filtered }
function foo() {
return apply_filters(
‘foo_data’,
array(
‘bar’,
‘baz’,
)
);
}

7. Micro-MVC
• Model = Get / prep data
• Controller = Do something with it
• View = Return / Output

8. Example
// munged controller / view // controller
foreach ($items as $item) { $_items = array();
$item->prop = utility($item); foreach ($items as $item) {
echo [$item...]; $item->prop = utility($item);
} $_items[‘id_’.$item->id] = $item;
}
$items = $_items;
// we can insert another step here
// easily when refactoring
// view
foreach ($items as $item) {
echo [$item...];
}

9. Getting / Saving Data
• Basic utility (method on a Model)
• Run everything through this
• Do thosecheck permissions/validation
(do
not
in a Controller)
• One place to make changes
• Easier refactoring

10. Recap
• Transparency FTW
• Developing = Refactoring
• Embrace MVC

11. Dev Plans, Comments &
Commit Messages
• Convey intent
• When code cannot be readable,
outline what the code is doing
• Document decisions