web development

Readme Driven Development

If you’ve ever had a project without a README file hosted at GitHub, you know the recommendation message to create one. When I first saw that message, I thought it was a bit weird, but, I guess, fine. It never bothered me enough to search for any explanation – I just ignored it, or created a README file. Apparently, there is an explanation – Readme Driven Development by Tom Preston-Werner, one of the GitHub co-founders.

By writing your Readme first you give yourself some pretty significant advantages:

Most importantly, you’re giving yourself a chance to think through the project without the overhead of having to change code every time you change your mind about how something should be organized or what should be included in the Public API. Remember that feeling when you first started writing automated code tests and realized that you caught all kinds of errors that would have otherwise snuck into your codebase? That’s the exact same feeling you’ll have if you write the Readme for your project before you write the actual code.

As a byproduct of writing a Readme in order to know what you need to implement, you’ll have a very nice piece of documentation sitting in front of you. You’ll also find that it’s much easier to write this document at the beginning of the project when your excitement and motivation are at their highest. Retroactively writing a Readme is an absolute drag, and you’re sure to miss all kinds of important details when you do so.

If you’re working with a team of developers you get even more mileage out of your Readme. If everyone else on the team has access to this information before you’ve completed the project, then they can confidently start work on other projects that will interface with your code. Without any sort of defined interface, you have to code in serial or face reimplementing large portions of code.

It’s a lot simpler to have a discussion based on something written down. It’s easy to talk endlessly and in circles about a problem if nothing is ever put to text. The simple act of writing down a proposed solution means everyone has a concrete idea that can be argued about and iterated upon.

Consider the process of writing the Readme for your project as the true act of creation. This is where all your brilliant ideas should be expressed. This document should stand on its own as a testament to your creativity and expressiveness. The Readme should be the single most important document in your codebase; writing it first is the proper thing to do.

HTML5 splits into two standards

Just when web developers got a little bit of hope, Slashdot reports on the bad news.

Until now the two standards bodies working on HTML5 (WHATWG and W3C ) have cooperated. An announcement by WHATWG makes it clear that this is no longer true. WHATWG is going to work on a living standard for HTML which will continue to evolve as more technologies are added. W3C is going the traditional and much more time consuming route of creating a traditional standard which WHATWG refers to as a ‘snapshot’ of their living standard. Of course now being free of W3C’s slower methods WHATWG can accelerate the pace of introducing new technologies to HTML5. Whatever happens, the future has just become more complicated — now you have to ask yourself ‘Which HTML5?’

Even if it sounds good, it is actually really bad. HTML5 is already complicated enough, and all major browsers support a different subset of it, and even those things which are supported do differ in the way of how. Splitting the standard just complicated things further. The fact that this is not exactly new, doesn’t really matter. Saying that it won’t be harmful, is silly. As is the whole point of a “living standard”. Like a few people mentioned in Slashdot comments, “living standard” is an oxymoron. The whole point of standard is to provide a static point of reference. Splitting is not a solution to the problem. It’s quite the opposite. Consider this xkcd comics for illustration, which is nothing but the truth.

wp-config.php and standalone scripts

WordPress plugin architecture is great and it provides developers with a lot of flexibility. But once in a while one needs to write a standalone script that should use some of WordPress settings. For example, a script that would have the same database credentials as a WordPress instance. This sounds simple unless you look at the bottom of the wp-config.php file. There’s that:

/** Sets up WordPress vars and included files. */
require_once(ABSPATH . 'wp-settings.php');

That means if you are to include wp-config.php in your standalone script, you’ll get the whole WordPress thing loaded and fired up. On one hand, that’s cool because now you can use WordPress functions and objects. But on the other, it’s not. Sometimes you just need the configuration only.

The work around is trivial. Modify wp-config.php file like so:

if (!defined('WP_CONFIG_ONLY')) {
    /** Sets up WordPress vars and included files. */
    require_once(ABSPATH . 'wp-settings.php');
}

Now, in your standalone scripts, you can do the following:

define('WP_CONFIG_ONLY', true);
require 'wp-config.php';

And you’ll only get WordPress configuration without any extras. If you don’t define the WP_CONFIG_ONLY constant before loading the wp-config.php, then all will work as before.

wp-config.php and git

If you are storing your WordPress changes in git and then deploy the project between different machines (local, test server, production environment, etc), then you are probably familiar with a problem of wp-config.php file. WordPress uses it for things like database credentials, which vary from machine to machine. But you can’t just ignore the file since it’s plays the role in WordPress bootstrap. The solution that we are using at work is very simple: have an additional configuration file, such as wp-config-local.php, which defines local settings, and which is ignored from git.

Here is how to do this. First, you need to create the file itself. Let’s say we want to change the database credentials which WordPress should use on the current machine. Create a file wp-config-local.php with the following content:

<?php
define('DB_HOST', 'localhost');
define('DB_USER', 'localdev');
define('DB_PASSWORD', 'code15poetry');
define('DB_NAME', 'wp_playground');
?>

Now we need to include the file from the wp-config.php. The local configuration file should be optional, so we only use it on those machines that need it. Here is the code that I’ve added to the top of my wp-config.php:

// Load wp-config-local.php
$localConfig = dirname(__FILE__) 
    . DIRECTORY_SEPARATOR . 'wp-config-local.php';
if (file_exists($localConfig) && is_file($localConfig) 
    && is_readable($localConfig)) {
    require_once $localConfig;
}

If you will have a look at your WordPress website now, it’ll probably be broken. That’s because you are not allowed to redefine constants. We’ve defined that in our wp-config-local.php which loads first, and then they are defined in the wp-config.php as well. We should work around this. For any constant that is defined in wp-config.php and which you want to be able to set from wp-config-local.php, change the line in wp-config.php like so:

// before
// define('DB_USER', 'root');
// after
if (!defined('DB_USER')) { define('DB_USER', 'root'); }

With this, you’ll basically have values in wp-config.php act as defaults. If there is no local configuration, they will be used. Otherwise, the local ones will be utilized.

The last tiny bit that you need to do is add wp-config-local.php to your .gitignore file. That’s it. Now commit, push, and enjoy.

Intermediate Rails: Understanding Models, Views and Controllers

BetterExplained.com better explains the MVC pattern. The examples are using Ruby on Rails, but that’s irrelevant. Many other MVC implementations in web frameworks are working in exactly the same manner. If you are not familiar or not very comfortable with MVC, read the article. It will make things clearer.