Why I Did What I Did – Coding for Maintainability

Here is what I spent all day working on today.  I replaced a large block of mixed HTML/PHP code that looked like this…

	$current_value      =& MyMirrors::$options->current_mode();
				
	$multi = is_multisite();
	$plus  = FALSE;
	$ultra = FALSE;
				
	$radios = array(DefaultsII::BLOG_CONTROL=>array((TRUE          ), esc_attr( 'Blog',                            'my-mirrors')),
				    DefaultsII::MULT__BLOG_1=>array(($multi        ), esc_attr( 'MultiSite via Blog 1',            'my-mirrors')),
				    DefaultsII::MULT_NETWORK=>array(($multi        ), esc_attr( 'MultiSite via Network Admin',     'my-mirrors')),
				    DefaultsII::BLOG__MANUAL=>array((        $plus ), esc_attr( 'Blog Remote (Manual)',            'my-mirrors')),
				    DefaultsII::BLOG____SYNC=>array((        $ultra), esc_attr( 'Blog Remote (Synchronized)',      'my-mirrors')),
				    DefaultsII::MULTI_MANUAL=>array(($multi&&$plus ), esc_attr( 'MultiSite Remote (Manual)',       'my-mirrors')),
				    DefaultsII::MULTI___SYNC=>array(($multi&&$ultra), esc_attr( 'MultiSite Remote (Synchronized)', 'my-mirrors')));

				 <?php if (MyMirrors::$options->allow_modes()) : 
				 
				 $radio_group     = new RadioGroupII('Initial_Mode', $current_value, $radios);
				 $html_for_radio_buttons =     $radio_button_group->html_of_input();

				 echo($html_for_radio_buttons);

Now, the original is the classic way of doing webpages.  Unfortunately, While this style works well for small, simple things, it breaks down for large complex projects like WordPress plugins.  The problem is that many levels of abstraction are all present at once.

This “everything in one view” style makes it easy to see “what’s on the page”; it obfuscates “what is the code doing”.  It is great for the presentation orientation, and problematic for the process action orientation.  

Now the entire “display” is replaced by one line:

echo($html_for_radio_buttons);

We had half of a page to display one small set of radio buttons, now we have one line.  “The radio buttons are here”

To do that, we created the HTML for the radio buttons using the class method html_of_input() which operated on the previously created object $radio_button_group. $radio_button_group, in turn, by instantiating the class RadioGroupII, thus:

$radio_group = new RadioGroupII('Initial_Mode', $current_value, $radios);

All of the HTML details are hidden elsewhere; we don’t need to know all that to understand the function of the code.  Stripped of all of that detail, it is easy to see that the radio button group named 'Initial_Mode' is displaying and altering the variable $current_value, and that the setup for the group is in the array $radios.

Before explaining the how and why of the $radios array, which is the heart of the code here, a bit of explanation of the setup.

This is the My Mirrors plugin, so the class MyMirrors is the main class; nearly everything is either in that class or in a class which that main class uses.  $current_value is a shorthand reference to one of the main static variables in that class.  $multi, $plus, and $ultra are booleans that describe what is available in the software environment, what options are allowed to be selected.  Unavailable options will simply not be displayed.

The array $radios is an exercise in displaying what is relevant to the future maintenance programmer, and hiding what is irrelevant.  It is an array of two dimensions; the keys for the outer array are shown, while the keys for the inner arrays are not.  This is a deliberate choice.  In an earlier incarnation, the inner keys were also shown.  This made a very messy and busy display, and the essential details faded to obscurity.

	$radios = array(DefaultsII::BLOG_CONTROL=>array((TRUE          ), esc_attr( 'Blog',                            'my-mirrors')),
				    DefaultsII::MULT__BLOG_1=>array(($multi        ), esc_attr( 'MultiSite via Blog 1',            'my-mirrors')),
				    DefaultsII::MULT_NETWORK=>array(($multi        ), esc_attr( 'MultiSite via Network Admin',     'my-mirrors')),
				    DefaultsII::BLOG__MANUAL=>array((        $plus ), esc_attr( 'Blog Remote (Manual)',            'my-mirrors')),
				    DefaultsII::BLOG____SYNC=>array((        $ultra), esc_attr( 'Blog Remote (Synchronized)',      'my-mirrors')),
				    DefaultsII::MULTI_MANUAL=>array(($multi&&$plus ), esc_attr( 'MultiSite Remote (Manual)',       'my-mirrors')),
				    DefaultsII::MULTI___SYNC=>array(($multi&&$ultra), esc_attr( 'MultiSite Remote (Synchronized)', 'my-mirrors')));

In the form it is given here, we see the three essential elements to every entry:

• What the option is. (MULT_NETWORK etc.)
• Whether is is enabled. (MULT_NETWORK is available if $multi is TRUE)
• What is the translatable label that the user will see (“MultiSite via Network Admin“)

(The final “my-mirrors” is an unavoidable WordPress requirement.)

The key for each row is important in understanding the code; the internal keys that distinguish the enabling switch from the label are not.

Note that the keys are given symbolically rather than by value. “Magic Numbers” and “Magic Strings” as keys are the constant nightmare of the maintenance programmer.  Here we have where the keys are defined (DefaultsII, where they are defined “once and only once” as intelligible strings), and a meaningful name for each.

However, the keys to the inner array items do exist, albeit not in the source array.  The constructor for the RadioGroupII class handles the translation from group order to named key values.

	CONST ALLOW = 'Allow';
	CONST LABEL = 'Label';
	CONST MAP   = array(self::ALLOW, self::LABEL);
	
	      foreach ($my_definition as $mode=>&$rad_def) {
	      	$def  =& $this->definition[$mode];
	      	$list =  $rad_def;
	      	$map  =  self::MAP;
		      foreach ($map as $place=>&$key) {
		      	$def[$key] = current($list);
		      	next($list);
		      }
		  }