- Correct: BDD

A slow Porsche isn’t going to get you any ladies, and incorrect software isn’t going to meet your business objectives. If software isn’t correct, it really doesn’t solve the problem it was supposed to solve. Correct software is software that works the way it was supposed to. To produce correct software, I like Behaviour-Driven Development (BDD). BDD revolves around writing software specs that are testable with statements like:

Given [initial context], when [event occurs], then [ensure some outcomes].

In order to generate the tests for BDD, collaboration is needed between developers, QA, and the non-technical business guys. This collaboration makes sure that 1) the problem is understood and 2) informs everyone as to what the solution to the problem looks like. Often time software is incorrect because the developer didn’t understand #1 or the client didn’t understand #2.

Here’s an example BDD test using Mocha:

describe('Array', function(){
  describe('#indexOf()', function(){
    it('should return -1 when the value is not present', function(){
      [1,2,3].indexOf(5).should.equal(-1);
      [1,2,3].indexOf(0).should.equal(-1);
    })
  })
})

- Robustness: Tests & Abstraction

By subjecting every input on a web page to a standard battery of tests you can generally catch common faults in robustness. The test suite should include a variety of ridiculous values which might include things like numbers in text fields, text in number fields, blanks in required fields, foreign characters, html entities, URL component separators, and others. Selenium and other UI test suites are good candidates for this, but can take a long time to setup, run, and maintain.

But even with good tests, keep in mind what E. Dijkstra said “testing shows the presence, not the absence of bugs”.

Using abstraction layers to scrub user input is also a great way to build robust systems. The abstraction layer provides a single location where the cleaning logic resides, and keeps your code base clear of repetitive tasks like converting NULL values to empty strings (should your application need such logic) or avoiding division by zero.

And because it’s hard to anticipate every “wrong” input, the abstraction layer provides a way to add additional robustness with little effort. The abstraction layer can be as simple as good routines. Here’s an example from Code Complete where Steve demonstrates the value of a routine, that consisted of just one line of code, when additional robustness was later needed:

Function DeviceUnitsToPoints ( deviceUnits Integer ): Integer
  DeviceUnitsToPoints = deviceUnits * ( POINTS_PER_INCH / DeviceUnitsPerInch() )
End Function

Which was updated once it was discovered that DeviceUnitsPerInch() might return 0:

Function DeviceUnitsToPoints ( deviceUnits Integer ): Integer
  If ( DeviceUnitsPerInch() <> 0 )
    DeviceUnitsToPoints = deviceUnits
                        * ( POINTS_PER_INCH / DeviceUnitsPerInch() )
  Else
    DeviceUnitsToPoints = 0
  End If
End Function

- User-friendliness: Failover AJAX

The fact of the matter is most people don’t like using computers. There is a handful of us out there that do, and we’re weird. The weird people that speak computer are in the minority, so it makes sense that most software isn’t written for that crowd. Software is written for the majority, which don’t speak computer.
With this fundamental principle understood it’s important to make software enjoyable to use. Any hurdle and it’s game over. The problem is that user-friendly software is hard. I like writing console apps, they’re quick to build, and they’re easy to test. But they’re a pain to use. I find myself using “–help” more often than I would like to omit for apps that I wrote!

When it comes to web apps you need to keep the number of clicks down, place related information together, and explain errors (when they occur) in plain English. I’m not a graphic designer or information architect, so I’ll steer clear of the UI stuff and elaborate on user friendliness when it comes to error reporting.

If an ajax call fails, we don’t want to leave the user hanging. We want to tell them that they need to login again, try the action again, or provide a valid value… something.
We can do that by writing the javascript with a failover. In other words, if the AJAX fails, the code handles it with a backup plan. Usually we think of failover in terms of robustness, but for web applications I really like to put this into the User-friendly category because it makes using the web much more enjoyable when done right.

Here’s an example that looks for oData['success'] and if the success property is set to false, or isn’t even present (like a 500 error might produce) the js displays an error.

Here we use the OR operator to test for the success property, which produces the failover:

//ajax that "fails over"
$.get(href, function (oData, textStatus) { 

  if ( oData['success'] || false ) {
    tgt.after("" + (oData['success'] || 'Subscription added.') + "");
    $("#subsvcmsg").attr("id", "").fadeOut(2500, function() { $(this).remove(); }); 

  } else {
    tgt.after("" + (oData['error']
      || 'An unknown error occurred trying to modify that subscription') + "");
    $("#subsvcmsg").attr("id", "").fadeOut(2500, function() { $(this).remove(); }); 

  }
});

This approach assumes you’re always passing back JSON, which I think is a nice way to go, but something similar can we done with xml, text, etc. In this example common errors like a stale session can be managed server side with details sent to the user on logging in again. But even if we don’t catch the error we tell the user that we didn’t save their change so they aren’t left guessing. And keeping users from guessing is the core of user-friendly design.

Dan Wooster recently asked what I thought about those attributes. My immediate reaction was that they’re a great description of what high quality code looks like. But I asked myself:

What is it about those attributes that are so great? Why do those attributes go hand in hand with high quality code?

Software has been around for a while, but “hardware” has been around for much longer. In this context, when I say “hardware” I’m referring to stuff like buildings, spoons, or your underwear. And because hardware has been around for so long, we’ve been designing hardware for a very long time. For example, since the inception of the wheel we’ve been trying to make a better cart. I won’t say we’ve perfected carts yet, but a Porsche 944 is probably as close as we’ll get.

Engineering, the study of how to design hardware, has been around for so long that we’ve started to study Engineering itself. When we boil down Engineering to its syrupy-goodness we find that it’s really about solving problems. After all, the hardware that engineering produces fills a need that we have: going down the highway really fast and attracting the ladies.

What does this have to do with programming? Code solves problems, just like cars solve problems. And the things that we know about the engineering of hardware applies to the engineering of software. When we approach a problem in the digital world, we solve it just like problems in the physical world. The application of engineering in both cases should produce a high quality solution, whether tangible like a Porsche 944, or intangible like my blog.

Defining “high quality” for things like Porches is easy: does it go fast and do the ladies flock in your direction. Doing so for software isn’t so easy because, well it’s intangible. Okay so maybe a 944 is high quality for more than just going fast and being a chic magnet. In fact, I’d say that a 944 exhibits those ten attributes I got started with. Again, good engineering produces high quality stuff, regardless of whether the stuff is tangible or intangible.

There’s lots of web “developers” out there that fail to engineer the code they write. The result is the same as if we were to build a car without engineering. Imagine if you had a car that lacked any of these attributes, and then think about what that means for software that is lacking the same:

- Correct (Works)

Car: Does the engine run, lights work, and breaks engage?
Software: Does the software do what it is suppose to do (according to the design specs)?

- Robustness

Car: Can you use unleaded gasoline from any fueling station, or just the one at the dealership? Can you turn on the radio while the windows are both up and down? Those are silly… what if you misuse the brakes: slam your foot to the floor? Do the wheels lock and skid or do they “anti-lock”?
Software: Does the software respond to unexpected conditions (wrong input)?

- User-friendliness

Car: Do you need to hand crank the engine, or can you just turn a key? Can you go forwards and backwards, or do you need to get out and push to back out?
Software: Is the software easy to use by users from the intended audience?

- Adapt-ability

Car: Can you change out the tires on snowy days, or put in special headlights?
Software: How difficult is it to modify the software to adjust to an ever-changing world?

- Reuse-ability

Car: Can the oil filter on your car be used on other cars, or do you need a trip to the dealership for the specific one made just for your make and model?
Software: can parts of the software be easily reused to build other software systems?

- Interoper-ability

Car: Do the rear brakes and front brakes work together or do you need two brake pedals?
Software: Does the software interface with other software systems?

- Efficiency

Car: Do you get 30 miles per gallon, or 10 gallons per mile?
Software: Does the software make good use of its resources (memory, disk, CPU, network)?

- Port-ability

Car: Can you use your car in different states, types of roads, and speeds?
Software: Can the software be easily ported (moved) to other operating systems (or in today’s world, browser)?

- Security

Car: Are you protected by seat belts, airbags, auto-shutoff fuel pumps, etc.
Software: Does the software protect the information it is responsible for?

- Replace-ability

Car: Can you get a new muffler, or does a hole in the exhaust mean buying a new car?
Software: can the software be easily replaced someday?

No one would put up with a car that doesn’t start, only takes gas from the dealership, requires you get out and push to back it up, can’t adapt to night because there’s no lights, costs a fortune because it’s made of all custom built parts, has two brake pedals, burns 10 gallons of gas per mile, can only drive in one state, has no safety features, and requires a new car whenever the muffler goes bad.

No one should put up with software like that either.

Part Two-
Engineering Code: Thinking Practically

However, when working on big queries with a team or reviewing logged errors from stored procedures, using the line numbers in Management Studio is invaluable.

Tools > Options
Expand the Text Editor node
Select the All Languages node
Under the Display header in the right pane, check the Line Numbers box

In the jQuery docs there’s a jQuery UI Autocomplete Combobox Plugin. Since we use jQuery and the UI, I started with this code and did a simple update around where the autocomplete input is blanked out for “invalid” inputs:

if ( !valid && select.data("prevent_input") )

The “prevent_input” setting will prevent the user from providing their own values if set to true (works like a standard select). Or it will allow user provided values if set to false (works like a standard input).

Configuring the input with jQuery data lets us set a default value like this:

<select id="your_select_id" data-prevent_input="true"/>
...
$('#your_select_id').combobox();

Note that the default behavior is to allow user provided values, but could be easily set to work the other way around.

Using jQuery.data() lets us change the behavior if your application needs to dynamically update this functionality:

jQuery('#your_select_id').data("prevent_input", false);

Here’s the plugin:

/**
 * jQuery UI Autocomplete Combobox Plugin
 *
 * Customized to allow users to type in arbitrary values
 *
 * @author dand
 * @since 10/21/2011
 * @see http://jqueryui.com/demos/autocomplete/#combobox
 */
(function( $ ) {
	$.widget( "ui.combobox", {
		_create: function() {
			var self = this,
				select = this.element.hide(),
				selected = select.children( ":selected" ),
				value = selected.val() ? selected.text() : "";
			var input = this.input = $( '<input id="' + select.attr('id').replace(/_options/,'') + '">' )
				.insertAfter( select )
				.val( value )
				.autocomplete({
					delay: 0,
					minLength: 0,
					source: function( request, response ) {
						var matcher = new RegExp( $.ui.autocomplete.escapeRegex(request.term), "i" );
						response( select.children( "option" ).map(function() {
							var text = $( this ).text();
							if ( this.value && ( !request.term || matcher.test(text) ) )
								return {
									label: text.replace(
										new RegExp(
											"(?![^&;]+;)(?!<[^<>]*)(" +
											$.ui.autocomplete.escapeRegex(request.term) +
											")(?![^<>]*>)(?![^&;]+;)", "gi"
										), "<strong>$1</strong>" ),
									value: text,
									option: this
								};
						}) );
					},
					select: function( event, ui ) {
						ui.item.option.selected = true;
						self._trigger( "selected", event, {
							item: ui.item.option
						});

					},
					change: function( event, ui ) {
						if ( !ui.item ) {
							var matcher = new RegExp( "^" + $.ui.autocomplete.escapeRegex( $(this).val() ) + "$", "i" ),
								valid = false;
							select.children( "option" ).each(function() {
								if ( $( this ).text().match( matcher ) ) {
									this.selected = valid = true;
									return false;
								}
							});

							if ( !valid && select.data("prevent_input") ) {
								// remove invalid value, as it didn't match anything
								$( this ).val( "" );
								select.val( "" );
								input.data( "autocomplete" ).term = "";
								return false;
							}
						}
					}
				})
				.addClass( "ui-widget ui-widget-content ui-corner-left" );

			input.data( "autocomplete" )._renderItem = function( ul, item ) {
				return $( "<li></li>" )
					.data( "item.autocomplete", item )
					.append( "<a>" + item.label + "</a>" )
					.appendTo( ul );
			};

			this.button = $( "<button type='button'>&nbsp;</button>" )
				.attr( "tabIndex", -1 )
				.attr( "title", "Show All Items" )
				.insertAfter( input )
				.button({
					icons: {
						primary: "ui-icon-triangle-1-s"
					},
					text: false
				})
				.removeClass( "ui-corner-all" )
				.addClass( "ui-corner-right ui-button-icon" )
				.click(function() {
					// close if already visible
					if ( input.autocomplete( "widget" ).is( ":visible" ) ) {
						input.autocomplete( "close" );
						return;
					}

					// work around a bug (likely same cause as #5265)
					$( this ).blur();

					// pass empty string as value to search for, displaying all results
					input.autocomplete( "search", "" );
					input.focus();
				});
		},

		destroy: function() {
			this.input.remove();
			this.button.remove();
			this.element.show();
			$.Widget.prototype.destroy.call( this );
		}
	});
})( jQuery );

Our customer loved the solution because it was both what they wanted AND cheap since it was fast to develop. Hope you enjoy!

Don’t let users have the opportunity to enter garbage data. If you do, they will. It’s just one of those laws of the universe. Thermodynamics?

Here’s the error:

UPS: 111286: {Provided State} is not a valid state for the specified shipment.

The state the user provided was:

On

Why didn’t that work? The state codes are case sensitive, and must be exact. Changing the customer’s address to use the following solved the problem:

ON

Note: I’ve seen other people with this problem on the web. They complained about values like “Ontario” not being valid. Don’t let the user provide bad inputs, give them a select list of valid state codes.

The problem was I would get the following errors when there were spaces in my merge file paths. For a path like /path/to the/file.rb I would get something like:

Incorrect parameters:
Too many files: You may enter a maximum of 4 files.
'/path/to' is (or points to) an invalid file.
'the/file.rb' is (or points to) an invalid file.
...

Here’s the easy solution that fixed this problem on my system:

[merge]
    keepBackup = false
	tool = custom
[mergetool "custom"]
	cmd = /Applications/p4merge.app/Contents/Resources/launchp4merge "\"$PWD/$BASE\"" "\"$PWD/$REMOTE\"" "\"$PWD/$LOCAL\"" "\"$PWD/$MERGED\""
	keepTemporaries = false
	trustExitCode = false
	keepBackup = false

Notice the extra (escaped) quote marks around the parameters. This could also be handled with a shell script, but I didn’t want an extra moving part to make the magic happen. Life is already complicated…

And me at my standing desk:

// Begin actual Duff's Device
// JS Implementation by Jeff Greenberg 2/2001

var n = iterations / 8;
var caseTest = iterations % 8;    

do {

    switch (caseTest){
    case 0:              [Do Something to tesVal here];
    case 7:              [Do Something to tesVal here];
    case 6:              [Do Something to tesVal here];
    case 5:              [Do Something to tesVal here];
    case 4:              [Do Something to tesVal here];
    case 3:              [Do Something to tesVal here];
    case 2:              [Do Something to tesVal here];
    case 1:              [Do Something to tesVal here];

    }
    caseTest=0;

}

while (--n > 0);

//Inside my view
<select id="exp_month" name="exp_month">
	<?php MonthList() ?>
</select>

<select id="exp_year" name="exp_year">
	<?php YearList() ?>
</select>

//In your model/controller or some other place you like to keep random stuff like this
/**
 * Populate the credit card expiration month drop down
 */
function MonthList(){
	for($i=0; $i<=11; $i++){
		$time = mktime(0, 0, 0, 1+$i, 1, 2000);
		$sMonthOptions .= '<option value="' . date('m', $time) . '">' . date('M', $time) . '</option>';
	}
	echo $sMonthOptions;
}

/**
 * Populate the credit card expiration year drop down (go out 12 years)
 */
function YearList(){
	for($i=0; $i<=11; $i++){
		$nextyear = date("Y", mktime(0, 0, 0, 1, 1, date("Y")+$i));
	    $sYearOptions .= '<option value="' . $nextyear . '">' . $nextyear . '</option>';
	}
	echo $sYearOptions;
}

Disclaimer: I have no idea if 12 years is “enough”, nor if this is the most “efficient” way of doing this. I also think a static html droplist of the months would be better… I don’t think we’re adding new months any time soon.

1) Ruby (and Rails)
[okay... this is coming...]

3) “Fix” Rake

$ gem uninstall rack
$ gem install rack -v 1.0.1

2) MySQL
(you need this even for a remote database, as it provides the necessary headers so we can install the drivers in step #4)

$ sudo yum remove mysql-server
$ sudo yum install mysql mysql-devel gcc

4) MySQL Gem

# 32 bit machine
$ sudo gem install mysql -- \
> --with-mysql-include=/usr/bin/mysql \
> --with-mysql-lib=/usr/lib/mysql

# or 64 bit like they are on SliceHost
$ sudo gem install mysql -- \
> --with-mysql-include=/usr/bin/mysql \
> --with-mysql-lib=/usr/lib64/mysq

5) Create databases (I like Sequel Pro)

webistrano_development
webistrano_test
webistrano_production

5) Configure Webistrano - database.yml

...
development:
  adapter: mysql
  database: webistrano_development
  username: [user here]
  password: [password here]
  host: [dbase subdomain].mysql.fathomdb.com
  port: [port number]
...

6) Install Webistrano!!!

$ cd [webistrano dir]
$ rake db:migrate

7) Open port for Webistrano (or use webmin)
Open-

/etc/sysconfig/iptables

Append rule-

-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 3000 -j ACCEPT

Restart the service

$ service iptables restart

Make sure iptables is allowing port 3000 connections:

$ iptables -L -n

8) DEPLOY SOMETHING!