Using events to remove some duplication from an Angular controller

In this post, we'll show how we're dealing with a controller which is less simple than the TrackDetailsPageController shown in previous posts.

This was the code of that controller in which we had already used the techniques specified in the two previous posts (extending Angular resources with behavior and moving logic to simple JavaScript widgets):

	"use strict";
	app.controller('TracksIndexPageController', [
	'$scope',
	'Categories',
	'accumulatedStatistics',
	'categoryListWidgetFactory',
	'dateRangeWidgetFactory',
	'Pagination',
	'activitiesWidgetFactory',
	function ($scope, Categories, accumulatedStatistics, categoryListWidgetFactory, dateRangeWidgetFactory, Pagination, activitiesWidgetFactory) {
	var updatePageInfo = function () {
	$scope.activities.filterBy($scope.categoryList.getSelectedCategory());
	$scope.updateActivitiesRelatedData();
	$scope.pagination = new Pagination($scope.activities.displayedOnes);
	},
	loadActivities = function () {
	$scope.activities.load(
	$scope.dateRange,
	updatePageInfo
	);
	};
	$scope.selectCategory = function (category) {
	if ($scope.categoryList.noActivitiesMatching(category)) {
	return;
	}
	$scope.categoryList.selectCategory(category);
	updatePageInfo();
	};
	$scope.loadMonthActivities = function () {
	$scope.dateRange.useMonthPeriod();
	loadActivities();
	};
	$scope.loadWeekActivities = function () {
	$scope.dateRange.useWeekPeriod();
	loadActivities();
	};
	$scope.loadYearActivities = function () {
	$scope.dateRange.useYearPeriod();
	loadActivities();
	};
	$scope.loadCurrentDateRangeActivities = function () {
	$scope.dateRange.today();
	loadActivities();
	};
	$scope.loadNextDateRangeActivities = function () {
	$scope.dateRange.forwards(1);
	loadActivities();
	};
	$scope.loadPreviousDateRangeActivities = function () {
	$scope.dateRange.backwards(1);
	loadActivities();
	};
	$scope.updateStatistics = function () {
	$scope.displayedStatistics = accumulatedStatistics.getGroupedStatisticsToDisplay(
	$scope.activities.displayedOnes
	);
	};
	$scope.updateActivitiesRelatedData = function () {
	$scope.updateStatistics();
	$scope.categoryList.updateNonEmptyCategories(
	$scope.activities.distinctCategories()
	);
	};
	$scope.userHasStatistics = function () {
	return accumulatedStatistics.exists();
	};
	$scope.shouldShowActivities = function () {
	return !resolved() || $scope.activities.thereAreSomeToDisplay();
	function resolved() {
	return _.isUndefined($scope.activities.displayedOnes.$resolved) ||
	$scope.activities.displayedOnes.$resolved;
	}
	};
	$scope.initialize = function () {
	$scope.Categories = Categories;
	$scope.categories = Categories.descriptions;
	$scope.activities = activitiesWidgetFactory.create();
	$scope.displayedStatistics = [];
	$scope.categoryList = categoryListWidgetFactory.create(Categories.allCategories);
	$scope.dateRange = dateRangeWidgetFactory.create();
	$scope.loadCurrentDateRangeActivities();
	};
	$scope.initialize();
	}
	]);

view raw TracksIndexPageController.js hosted with ❤ by GitHub

Even though most of the logic in this controller had been removed by using four widgets, (activities, dateRange, categoryList and pagination), there was still duplication in the functions that were doing the coordination among widgets (see functions: loadMonthActivities, loadWeekActivities, loadYearActivities, loadCurrentDateRangeActivities, loadNextDateRangeActivities, loadPreviousDateRangeActivities and selectCategory).

A way of getting rid of this code was using events.

We started by publishing a 'DateRange:Changed' event using the Angular's $rootScope.$broadcast from the updateRange function inside the dateRange widget and then added a listener for that event in the controller which loaded new activities every time that event was published. We also added some new convenience helpers to the dateRange widget in order to make it easier to use from the partial.

This was the resulting code of TracksIndexPageController after these changes:

	"use strict";
	app.controller('TracksIndexPageController', [
	'$scope',
	'Categories',
	'accumulatedStatistics',
	'categoryListWidgetFactory',
	'dateRangeWidgetFactory',
	'Pagination',
	'activitiesWidgetFactory',
	function ($scope, Categories, accumulatedStatistics, categoryListWidgetFactory, dateRangeWidgetFactory, Pagination, activitiesWidgetFactory) {
	var updatePageInfo = function () {
	$scope.activities.filterBy($scope.categoryList.getSelectedCategory());
	$scope.updateActivitiesRelatedData();
	$scope.pagination = new Pagination($scope.activities.displayedOnes);
	};
	$scope.selectCategory = function (category) {
	if ($scope.categoryList.noActivitiesMatching(category)) {
	return;
	}
	$scope.categoryList.selectCategory(category);
	updatePageInfo();
	};
	$scope.$on('DateRange:changed', function () {
	$scope.activities.load($scope.dateRange, updatePageInfo);
	});
	$scope.updateStatistics = function () {
	$scope.displayedStatistics = accumulatedStatistics.getGroupedStatisticsToDisplay(
	$scope.activities.displayedOnes
	);
	};
	$scope.updateActivitiesRelatedData = function () {
	$scope.updateStatistics();
	$scope.categoryList.updateNonEmptyCategories(
	$scope.activities.distinctCategories()
	);
	};
	$scope.userHasStatistics = function () {
	return accumulatedStatistics.exists();
	};
	$scope.shouldShowActivities = function () {
	return !resolved() || $scope.activities.thereAreSomeToDisplay();
	function resolved() {
	return _.isUndefined($scope.activities.displayedOnes.$resolved) ||
	$scope.activities.displayedOnes.$resolved;
	}
	};
	$scope.initialize = function () {
	$scope.Categories = Categories;
	$scope.categories = Categories.descriptions;
	$scope.activities = activitiesWidgetFactory.create();
	$scope.displayedStatistics = [];
	$scope.categoryList = categoryListWidgetFactory.create(Categories.allCategories);
	$scope.dateRange = dateRangeWidgetFactory.create();
	$scope.dateRange.today();
	};
	$scope.initialize();
	}
	]);

view raw TracksIndexPageControllerWithDateRangeEvents.js hosted with ❤ by GitHub

Notice how the functions loadMonthActivities, loadWeekActivities, loadYearActivities, loadCurrentDateRangeActivities, loadNextDateRangeActivities and loadPreviousDateRangeActivities have dissappeared and how this piece of code

	$scope.$on('DateRange:changed', function () {
	$scope.activities.load($scope.dateRange, updatePageInfo);
	});

view raw DateRangChangedListener.js hosted with ❤ by GitHub

was listening to the 'DateRange:Changed' event to reload the activities every time the date range changes.

Next, we did the same for the categoryList widget getting this new version of TracksIndexPageController:

	"use strict";
	app.controller('TracksIndexPageController', [
	'$scope',
	'Categories',
	'accumulatedStatistics',
	'categoryListWidgetFactory',
	'dateRangeWidgetFactory',
	'Pagination',
	'activitiesWidgetFactory',
	function ($scope, Categories, accumulatedStatistics, categoryListWidgetFactory, dateRangeWidgetFactory, Pagination, activitiesWidgetFactory) {
	var updatePageInfo = function () {
	$scope.activities.filterBy($scope.categoryList.getSelectedCategory());
	$scope.updateActivitiesRelatedData();
	$scope.pagination = new Pagination($scope.activities.displayedOnes);
	},
	updateStatistics = function () {
	$scope.displayedStatistics = accumulatedStatistics.getGroupedStatisticsToDisplay(
	$scope.activities.displayedOnes
	);
	};
	$scope.$on('DateRange:Changed',
	function () {
	$scope.activities.load($scope.dateRange, updatePageInfo);
	}
	);
	$scope.$on('CategoryList:NewCategorySelected',
	updatePageInfo
	);
	$scope.updateActivitiesRelatedData = function () {
	updateStatistics();
	$scope.categoryList.updateNonEmptyCategories(
	$scope.activities.distinctCategories()
	);
	};
	$scope.userHasStatistics = function () {
	return accumulatedStatistics.exists();
	};
	$scope.shouldShowActivities = function () {
	return !resolved() || $scope.activities.thereAreSomeToDisplay();
	function resolved() {
	return _.isUndefined($scope.activities.displayedOnes.$resolved) ||
	$scope.activities.displayedOnes.$resolved;
	}
	};
	$scope.initialize = function () {
	$scope.Categories = Categories;
	$scope.categories = Categories.descriptions;
	$scope.activities = activitiesWidgetFactory.create();
	$scope.displayedStatistics = [];
	$scope.categoryList = categoryListWidgetFactory.create(
	Categories.allCategories,
	$scope.activities.distinctCategories()
	);
	$scope.dateRange = dateRangeWidgetFactory.create();
	$scope.dateRange.today();
	};
	$scope.initialize();
	}
	]);

view raw TracksIndexPageControllerWithCategorySelectionEvent.js hosted with ❤ by GitHub

in which selectCategory was gone.

The duplication that we highlighted in the first version of the controller had been removed but there were still some things we didn't like in this code.

1. We were using strings to identify the events in different parts of the code (the widgets and the controller). This was a case of the magic numbers smell.
2. Now our widgets weren't simple JavaScript objects anymore because they were using Angular's $rootScope.$broadcast inside. This made their testing a bit more difficult.

We solved the first problem by putting the events identification strings in just one place:

	//
	// Events used in the application
	//--------------------------------------------------
	app.value("applicationEvents", {
	CategoryList_NewSelectedCategory: 'CategoryList:NewCategorySelected',
	UserProfile_Updated: 'UserProfile:Updated',
	Map_created: 'OpenLayersMap:created',
	DateRange_Changed:'DateRange:Changed'
	});

view raw applicationEvents.js hosted with ❤ by GitHub

To avoid the second problem and make our code easier to test we created a wrapper on Angular's $rootScope.$broadcast:

	// Wrapper on event publishing functionality
	//--------------------------------------------------
	app.service('eventPublisher', [
	'$rootScope',
	'applicationEvents',
	function ($rootScope, applicationEvents) {
	return {
	publish: function (eventType, payLoad) {
	$rootScope.$broadcast(eventType, payLoad);
	},
	events: applicationEvents
	};
	}
	]);

view raw eventPublisher.js hosted with ❤ by GitHub

This is a fragment of the current tests for the dateRange widget where we spy on eventPublisher to check that its publish method gets called whenever a function that updates the date range is called:

	//.. some code before
	//..
	describe("Updating date range publishes an event", function () {
	var dateRangeWidget;
	beforeEach(
	inject(function (DateRangePeriods) {
	dateRangeWidget = dateRangeWidgetFactory.create(DateRangePeriods.YEAR);
	spyOn(eventPublisher, "publish");
	})
	);
	it("publishes a DateRange:Changed event when the date range is updated to " +
	"the period containing the start date", function () {
	dateRangeWidget.containingCurrentStartDate();
	expect(eventPublisher.publish.calls.first().args)
	.toEqual([applicationEvents.DateRange_Changed, {}]);
	});
	it("publishes a DateRange:Changed event when the date range is updated to " +
	"the period after the start date", function () {
	dateRangeWidget.forwards(1);
	expect(eventPublisher.publish.calls.first().args)
	.toEqual([applicationEvents.DateRange_Changed, {}]);
	});
	it("publishes a DateRange:Changed event when the date range is updated to " +
	"the period after the start date", function () {
	dateRangeWidget.backwards(1);
	expect(eventPublisher.publish.calls.first().args)
	.toEqual([applicationEvents.DateRange_Changed, {}]);
	});
	});
	//..
	//.. some code after

view raw UpdatingDateRangePublishesAnEvent.js hosted with ❤ by GitHub

After all these changes this is the current version of TrackDetailsPageController:

	"use strict";
	app.controller('TracksIndexPageController', [
	'$scope',
	'Categories',
	'accumulatedStatistics',
	'categoryListWidgetFactory',
	'dateRangeWidgetFactory',
	'Pagination',
	'activitiesWidgetFactory',
	'applicationEvents',
	function ($scope, Categories, accumulatedStatistics, categoryListWidgetFactory, dateRangeWidgetFactory, Pagination, activitiesWidgetFactory, applicationEvents) {
	var updatePageInfo = function () {
	$scope.activities.filterBy($scope.categoryList.getSelectedCategory());
	$scope.updateActivitiesRelatedData();
	$scope.pagination = new Pagination($scope.activities.displayedOnes);
	},
	updateStatistics = function () {
	$scope.displayedStatistics = accumulatedStatistics.getGroupedStatisticsToDisplay(
	$scope.activities.displayedOnes
	);
	};
	$scope.$on(
	applicationEvents.DateRange_Changed,
	function () {
	$scope.activities.load($scope.dateRange, updatePageInfo);
	}
	);
	$scope.$on(
	applicationEvents.CategoryList_NewSelectedCategory,
	updatePageInfo
	);
	$scope.updateActivitiesRelatedData = function () {
	updateStatistics();
	$scope.categoryList.updateNonEmptyCategories(
	$scope.activities.distinctCategories()
	);
	};
	$scope.userHasStatistics = function () {
	return accumulatedStatistics.exists();
	};
	$scope.shouldShowActivities = function () {
	return !resolved() || $scope.activities.thereAreSomeToDisplay();
	function resolved() {
	return _.isUndefined($scope.activities.displayedOnes.$resolved) ||
	$scope.activities.displayedOnes.$resolved;
	}
	};
	$scope.initialize = function () {
	$scope.Categories = Categories;
	$scope.categories = Categories.descriptions;
	$scope.activities = activitiesWidgetFactory.create();
	$scope.displayedStatistics = [];
	$scope.categoryList = categoryListWidgetFactory.create(
	Categories.allCategories,
	$scope.activities.distinctCategories()
	);
	$scope.dateRange = dateRangeWidgetFactory.create();
	$scope.dateRange.today();
	};
	$scope.initialize();
	}
	]);

view raw TracksIndexPageControllerWithAllEvents.js hosted with ❤ by GitHub

Interesting Talk: "The Language of the System"

I've just watched again this great talk by Rich Hickey:

• The Language of the System

Interesting Talk: "DDD applied"

I've just watched this great talk (in Spanish) by Sergi González and Eloi Poch:

• DDD applied

Interesting Talk: "Embrace the asynchronous"

I've just watched this great talk by Rod Vagg:

• Embrace the asynchronous

Keeping Angular controllers complexity and size under control by using plain JavaScript widgets

Another problem I found while working on a legacy Angular application last year, was huge controllers with several hundreds of lines.

Most of those controllers contained a lot of procedural code and were doing too much. This made them very hard to test.

In the new Angular application we're currently working on, we're refactoring very aggressively to keep the size of our controllers small.

Apart from the strategy I talked about in a previous post, another technique that is giving us good results is extracting as much logic and state as possible from the controllers by moving related state and logic into small plain JavaScript objects that we call widgets.

This has had a huge impact in the testability of the code and helped us to keep the controllers size and complexity small.

Now I'll show you the results of one of this refactors, so that you can see its impact in a controller.

This is the first working version of a controller that is coordinating the behavior and content of a page showing details about a track. This page contains a map (using OpenLayers) with the polyline of the track on it, some statistics about the track and several charts (plotted using flot library)) to present some data from the track. It's possible to interact with these charts by changing the magnitude represented in their x axis (it can be distance or time):

	"use strict";
	app.controller('TrackDetailsPageController', [
	'$scope',
	'$routeParams',
	'Track',
	'trackStatisticsToDisplay',
	'Charts',
	'trackMap',
	'Categories',
	function ($scope, $routeParams, Track, trackStatisticsToDisplay, Charts, trackMap, Categories) {
	$scope.xAxis = Charts.defaultXAxis;
	$scope.options = {};
	$scope.chartTypes = Charts.defaultChartTypes;
	$scope.ChartDescriptions = Charts.descriptions;
	$scope.xAxisInDistanceUnits = function () {
	$scope.xAxis = Charts.xAxisInDistanceUnits;
	};
	$scope.xAxisInTimeUnits = function () {
	$scope.xAxis = Charts.xAxisInTimeUnits;
	};
	$scope.hasXAxisDistanceUnits = function () {
	return $scope.xAxis === Charts.xAxisInDistanceUnits;
	};
	$scope.hasXAxisTimeUnits = function () {
	return $scope.xAxis === Charts.xAxisInTimeUnits;
	};
	$scope.yUnits = function (chartType) {
	if ($scope.yUnitsByChartType) {
	return $scope.yUnitsByChartType[chartType];
	}
	};
	$scope.xUnits = function (chartType) {
	if ($scope.xUnitsByChartType) {
	return $scope.xUnitsByChartType[chartType]();
	}
	};
	$scope.track = Track.get({
	track_slug: $routeParams.track_slug
	},
	function (track) {
	$scope.groupedStatistics = trackStatisticsToDisplay.create(
	track.getStatistics()
	);
	var source = trackMap.getTrackPolylineSource(
	track.getUrl()
	);
	$scope.xUnitsByChartType = _.reduce(
	$scope.chartTypes,
	function (acc, chartType) {
	var scope = $scope;
	acc[chartType] = function () {
	return track.getXAxisUnits(chartType, scope.xAxis);
	};
	return acc;
	},
	{}
	);
	$scope.yUnitsByChartType = _.reduce(
	$scope.chartTypes,
	function (acc, chartType) {
	acc[chartType] = track.getYAxisUnits(chartType);
	return acc;
	},
	{}
	);
	source.once('change',
	function () {
	trackMap.addTrackPolylineToMap(
	$scope.routeMapInstance,
	source
	);
	}
	);
	}
	);
	$scope.getSportIconCssClass = function (category) {
	if (!category) {
	category = 'common.all_sports';
	}
	return 'svg-' + Categories.getSportIconCssClass(category);
	}
	$scope.$on('OLMaps:created', function (event, mapInstance) {
	if (mapInstance.key) {
	$scope[mapInstance.key] = mapInstance.map;
	}
	});
	}
	]);

view raw TrackDetailsPageController.js hosted with ❤ by GitHub

Notice how there are a lot of functions in the scope which are managing the state of the xAxis variable and getting information about the charts (x and y axis units, selected magnitude for x axis).

We had also this directive for the charts:

	app.directive('flotChart', [
	'$window',
	'Charts',
	'NumbersWithFixedDecimals',
	function ($window, Charts, NumbersWithFixedDecimals) {
	return {
	restrict: 'AE',
	scope: {
	data: '=flotData',
	graphicType: '=graphicType',
	options: '=flotOptions',
	plothover: '&plotHover',
	plotclick: '&plotClick',
	xAxis: '=xAxis'
	},
	link: function (scope, element, attr) {
	var plot = $.plot($(element), getPoints(), getOptions());
	$(element).bind('plothover', function (event, position, item) {
	scope.plothover({
	event: event,
	position: position,
	item: item
	});
	});
	$(element).bind('plotclick', function (event, position, item) {
	scope.plotclick({
	event: event,
	position: position,
	item: item
	});
	});
	scope.$watch('data', function (newVal, oldVal) {
	drawGraphics();
	}, true);
	scope.$watch('options', function (newVal, oldVal) {
	plot = $.plot($(element), getPoints(), getOptions());
	}, true);
	scope.$watch('xAxis', function (newVal, oldVal) {
	drawGraphics();
	});
	angular.element($window).bind('resize', function() {
	plot = $.plot($(element), getPoints(), getOptions());
	});
	function drawGraphics() {
	plot.setData(getPoints());
	plot.setupGrid();
	plot.draw();
	}
	function getPoints() {
	var roundNumberToTwoDecimals = NumbersWithFixedDecimals.toDecimals(2).round;
	if (!scope.data.$resolved) {
	return {
	data: []
	};
	}
	return [
	{
	data: roundCoordinatesToTwoDecimals(
	scope.data.graphics.data[scope.graphicType][scope.xAxis]
	)
	}
	];
	function roundCoordinatesToTwoDecimals(points) {
	return _.map(
	points,
	function (point) {
	return [
	roundNumberToTwoDecimals(point[0]),
	roundNumberToTwoDecimals(point[1])
	];
	}
	);
	}
	}
	function getOptions() {
	return _.extend(Charts.defaultOptions, scope.options);
	}
	}
	};
	}
	]);

view raw ChartsDirective.js hosted with ❤ by GitHub

which was being passed the selected x axis magnitude and the charts data.

We got to this version of the code after several design changes and quick spikes. Once we were happy with the UI behavior, it was time to stabilize it.

To do it we created a widget in an Angular factory which was a plain JavaScript object in charge of managing the state related to the charts (xAxis variable which was being read and mutated) and accessing the charts data (which were only being read):

	app.factory('chartsWidgetFactory', [
	'Charts',
	'chartPoints',
	function (Charts, chartPoints) {
	var trackWithCharts,
	chartTypesInTrack,
	chartTypes,
	xUnitsByChartType,
	yUnitsByChartType,
	chartOptions;
	return {
	create: function (track, options) {
	trackWithCharts = track;
	chartOptions = options || {};
	chartTypesInTrack = track.getChartsKeys();
	chartTypes = _.filter(
	Charts.defaultChartTypes,
	function (chartType) {
	return _.contains(chartTypesInTrack, chartType);
	}
	);
	xUnitsByChartType = _.reduce(
	chartTypes,
	function (acc, chartType) {
	acc[chartType] = function (xAxis) {
	return track.getXAxisUnits(chartType, xAxis);
	};
	return acc;
	},
	{}
	);
	yUnitsByChartType = _.reduce(
	chartTypes,
	function (acc, chartType) {
	acc[chartType] = track.getYAxisUnits(chartType);
	return acc;
	},
	{}
	);
	return {
	types: chartTypes,
	yUnits: function (chartType) {
	return yUnitsByChartType[chartType];
	},
	xUnits: function (chartType) {
	return xUnitsByChartType[chartType](this.xAxis);
	},
	xAxis: Charts.defaultXAxis,
	xAxisInDistanceUnits: function () {
	this.xAxis = Charts.xAxisInDistanceUnits;
	},
	xAxisInTimeUnits: function () {
	this.xAxis = Charts.xAxisInTimeUnits;
	},
	hasXAxisDistanceUnits: function () {
	return this.xAxis === Charts.xAxisInDistanceUnits;
	},
	hasXAxisTimeUnits: function () {
	return this.xAxis === Charts.xAxisInTimeUnits;
	},
	descriptionFor: function (chartType) {
	return Charts.descriptions[chartType];
	},
	options: chartOptions,
	extractPointsFor: function (chartType) {
	return chartPoints.extractFrom(track, chartType, this.xAxis);
	},
	track: track
	};
	}
	};
	}
	]);

view raw chartsWidget.js hosted with ❤ by GitHub

Notice how the widget is created by passing the track to the create method. This method initializes some values and returns the charts widget which has privileged access through a closure to several private functions and data.

We basically moved all the functions related to the charts that were before in the controller into the new widget and made some of them private.

After being moved to the widget, the logic controlling the charts became very easy to test using fake tracks:

	"use strict";
	describe("chartsWidgetFactory", function () {
	var chartData = {
	speed_graphics: {
	units: {
	distance: "km",
	speed: "km/h",
	time: "min"
	},
	with_respect_to_distance: [
	],
	with_respect_to_time: [
	]
	},
	elevations_graphics: {
	units: {
	distance: "km",
	elevation: "m",
	time: "min"
	},
	with_respect_to_distance: [
	],
	with_respect_to_time: [
	]
	}
	},
	fakeTrackWithCharts = {
	graphics: {
	data: chartData
	}
	},
	chartsWidgetFactory,
	chartPoints,
	trackMethods,
	charts;
	beforeEach(module("agora"));
	beforeEach(function () {
	module(function ($provide) {
	$provide.constant('Charts', {
	'defaultOptions': {
	},
	'descriptions': {
	'elevations_graphics': 'charts.elevations_graphics',
	'speed_graphics': 'charts.speed_graphics'
	},
	defaultXAxis: 'with_respect_to_distance',
	defaultChartTypes: [
	'elevations_graphics',
	'speed_graphics',
	'blabla1_graphics_that_it_is_not_in_track',
	'blabla2_graphics_that_it_is_not_in_track'
	],
	xAxisInDistanceUnits: "with_respect_to_distance",
	xAxisInTimeUnits: "with_respect_to_time"
	});
	});
	});
	beforeEach(
	inject(function (_chartsWidgetFactory_, _chartPoints_, _trackMethods_) {
	chartsWidgetFactory = _chartsWidgetFactory_;
	chartPoints = _chartPoints_;
	trackMethods = _trackMethods_;
	_.extend(fakeTrackWithCharts, trackMethods);
	charts = chartsWidgetFactory.create(fakeTrackWithCharts);
	})
	);
	it("initializes its xAxis property with the value of Charts.defaultXAxis",
	inject(function (Charts) {
	expect(charts.xAxis).toBe(Charts.defaultXAxis);
	})
	);
	it("initializes the chart types to only those chart types from Charts.defaultChartTypes " +
	"that are included in the track charts", function () {
	expect(charts.types).toEqual([
	'elevations_graphics',
	'speed_graphics'
	]);
	});
	it("gets the y axis units of a given chart", function () {
	expect(charts.yUnits('speed_graphics')).toBe('km/h');
	expect(charts.yUnits('elevations_graphics')).toBe('m');
	});
	it("gets the x axis units of a given chart by delegating on track " +
	"(which is augmented with trackMethods)",
	inject(function (Charts) {
	spyOn(fakeTrackWithCharts, "getXAxisUnits");
	charts.xUnits('elevations_graphics');
	expect(fakeTrackWithCharts.getXAxisUnits)
	.toHaveBeenCalledWith(
	'elevations_graphics',
	Charts.defaultXAxis
	);
	})
	);
	it("can set the x axis property of the charts",
	inject(function (Charts) {
	expect(charts.xAxis).toBe(Charts.defaultXAxis);
	charts.xAxisInTimeUnits();
	expect(charts.xAxis).toBe(Charts.xAxisInTimeUnits);
	charts.xAxisInDistanceUnits();
	expect(charts.xAxis).toBe(Charts.xAxisInDistanceUnits);
	})
	);
	it("has queries for the value of the x axis property of the charts", function () {
	charts.xAxisInTimeUnits();
	expect(charts.hasXAxisTimeUnits()).toBeTruthy();
	expect(charts.hasXAxisDistanceUnits()).toBeFalsy();
	charts.xAxisInDistanceUnits();
	expect(charts.hasXAxisTimeUnits()).toBeFalsy();
	expect(charts.hasXAxisDistanceUnits()).toBeTruthy();
	});
	it("gets the description of a given chart type",
	inject(function (Charts) {
	_.each(
	charts.types,
	function (chartType) {
	expect(charts.descriptionFor(chartType))
	.toBe(Charts.descriptions[chartType])
	}
	);
	})
	);
	it("delegates on chartPoints to extract the points of a given chart",
	inject(function (Charts) {
	spyOn(chartPoints, "extractFrom");
	charts.extractPointsFor('speed_graphics');
	expect(chartPoints.extractFrom)
	.toHaveBeenCalledWith(
	fakeTrackWithCharts,
	'speed_graphics',
	Charts.defaultXAxis
	);
	})
	);
	it("can initialize the charts options with a given object", function () {
	var someArbitraryOptions = {
	whateverOption: "whatever"
	},
	otherCharts = chartsWidgetFactory.create(
	fakeTrackWithCharts, someArbitraryOptions
	);
	expect(otherCharts.options).toEqual(someArbitraryOptions);
	});
	it("initializes the charts options to an empty object when no options are passed", function () {
	expect(charts.options).toEqual({});
	});
	});

view raw chartsWidgetSpec.js hosted with ❤ by GitHub

After this change the controller was reduced to this:

	"use strict";
	app.controller('TrackDetailsPageController', [
	'$scope',
	'$routeParams',
	'Track',
	'trackStatisticsToDisplay',
	'trackMap',
	'Categories',
	'chartsWidgetFactory',
	function ($scope, $routeParams, Track, trackStatisticsToDisplay, trackMap, Categories, chartsWidgetFactory) {
	$scope.track = Track.get({
	track_slug: $routeParams.track_slug
	},
	function (track) {
	$scope.groupedStatistics = trackStatisticsToDisplay.create(
	track.getStatistics()
	);
	var source = trackMap.getTrackPolylineSource(
	track.getUrl()
	);
	source.once('change',
	function () {
	trackMap.addTrackPolylineToMap(
	$scope.routeMapInstance,
	source
	);
	}
	);
	$scope.charts = chartsWidgetFactory.create(track);
	}
	);
	$scope.getSportIconCssClass = function (category) {
	if (!category) {
	category = 'common.all_sports';
	}
	return 'svg-' + Categories.getSportIconCssClass(category);
	};
	$scope.$on('OLMaps:created', function (event, mapInstance) {
	if (mapInstance.key) {
	$scope[mapInstance.key] = mapInstance.map;
	}
	});
	}
	]);

view raw TrackDetailsPageControllerWithChartExtracted.js hosted with ❤ by GitHub

Notice how all the chart-managing logic has disappeared from the controller. The only code related to the chart that remains is its creation.

We were also able to simplify the code of the directive by just passing it the new widget:

	"use strict";
	app.directive('flotChart', [
	'$window',
	'Charts',
	function ($window, Charts) {
	return {
	restrict: 'AE',
	scope: {
	graphicType: '=graphicType',
	plothover: '&plotHover',
	plotclick: '&plotClick',
	charts: '=charts'
	},
	link: function (scope, element, attr) {
	var plot = $.plot($(element), getPoints(), getOptions());
	$(element).bind('plothover', function (event, position, item) {
	scope.plothover({
	event: event,
	position: position,
	item: item
	});
	});
	$(element).bind('plotclick', function (event, position, item) {
	scope.plotclick({
	event: event,
	position: position,
	item: item
	});
	});
	scope.$watch('charts.track', function (newVal, oldVal) {
	drawGraphics();
	}, true);
	scope.$watch('charts.options', function (newVal, oldVal) {
	plot = $.plot($(element), getPoints(), getOptions());
	}, true);
	scope.$watch('charts.xAxis', function (newVal, oldVal) {
	drawGraphics();
	});
	angular.element($window).bind('resize', function() {
	plot = $.plot($(element), getPoints(), getOptions());
	});
	function drawGraphics() {
	plot.setData(getPoints());
	plot.setupGrid();
	plot.draw();
	}
	function getPoints() {
	if (!scope.charts.track.$resolved) {
	return {
	data: []
	};
	}
	return [
	{
	data: scope.charts.extractPointsFor(scope.graphicType)
	}
	];
	}
	function getOptions() {
	return _.extend(Charts.defaultOptions, scope.options);
	}
	}
	};
	}
	]);

view raw SimplifiedChartsDirective.js hosted with ❤ by GitHub

Notice how the widget has also absorbed the code that produced the points in the chart.

We have continued refactoring this controller and others in the same way. Making small refactors every time we detected duplication or discovered new concepts that could help us extract behavior from them.

This is the current code of the controller that we've been showing in this example:

	"use strict";
	app.controller('TrackDetailsPageController', [
	'$scope',
	'$routeParams',
	'trackStatisticsToDisplay',
	'trackMap',
	'chartsWidgetFactory',
	'tracksRepository',
	'CategoriesIcons',
	function ($scope, $routeParams, trackStatisticsToDisplay, trackMap, chartsWidgetFactory, tracksRepository, CategoriesIcons) {
	$scope.track = tracksRepository.getTrack(
	$routeParams.track_slug,
	function (track) {
	$scope.groupedStatistics = trackStatisticsToDisplay.create(
	track.getStatistics()
	);
	var source = trackMap.getTrackPolylineSource(track);
	source.once('change',
	function () {
	trackMap.addTrackPolylineToMap(
	$scope.routeMapInstance,
	source
	);
	}
	);
	$scope.charts = chartsWidgetFactory.create(track);
	}
	);
	$scope.CategoriesIcons = CategoriesIcons;
	$scope.$on('OLMaps:created', function (event, mapInstance) {
	if (mapInstance.key) {
	$scope[mapInstance.key] = mapInstance.map;
	}
	});
	}
	]);

view raw currentTrackDetailsPageController.js hosted with ❤ by GitHub

Keeping Angular controllers complexity and size under control is a constant effort that, having seen in other projects the negative effects of huge controllers, I think it's totally worth it.

Interesting Talk: "Crafted Design"

I've just watched this wonderful talk by Sandro Mancuso:

• Crafted Design

Avoid primitive-obsession-related problems by adding behavior to Angular resources using Underscore extend function

One of the problems I found while working on a legacy Angular application last year, was resources with deeply nested structures that were being accessed directly from many different places.

That code was revealing too much about the resources inner structure and that meant that the code that interacted with the resources was spread all over therefore generating a lot of duplication. That made it really hard to change and understand.

It was suffering from a severe case of primitive obsession in the form of directly using raw resources.

To prevent that from happening in the Angular application we are developing now, we have added behavior to Angular resources using Underscore extend function. By doing it, we have managed to hide the inner structure of the resources from its users and also created an object that has attracted the resource-handling code that was before spread all over.

These strategy has put us in a much better position. Now if the structure of the JSON data of a resource changes for any reason, we have only one place to go to adapt to that change.

It also has improved the overall readability of the code by making it possible to give proper names to the different resource-handling functions.

Here it's an example from our code:

	app.factory('Track', [
	'$http',
	'$resource',
	'dateStringsInsideObjectsIntoDates',
	'appendTransform',
	'ApiBaseUrl',
	'trackMethods',
	function (
	$http,
	$resource,
	dateStringsInsideObjectsIntoDates,
	appendTransform,
	ApiBaseUrl,
	trackMethods
	) {
	var Track = $resource(
	ApiBaseUrl + '/tracks/:track_slug',
	{'track_slug': '@slug'}, {
	'get': {
	method: 'GET',
	transformResponse: appendTransform(
	$http.defaults.transformResponse,
	function (value) {
	dateStringsInsideObjectsIntoDates.convert(value);
	return value;
	}
	)
	},
	'query': {
	method: 'GET',
	isArray: true,
	transformResponse: appendTransform(
	$http.defaults.transformResponse,
	function (value) {
	angular.forEach(value, function (item) {
	dateStringsInsideObjectsIntoDates.convert(item);
	});
	return value;
	}
	)
	},
	'getTracksWithoutData': {
	method: 'GET',
	isArray: true,
	ignoreLoadingBar: true
	},
	'update': { method: 'PUT' },
	'delete': { method: 'DELETE' }
	}
	);
	_.extend(Track.prototype, trackMethods);
	return Track;
	}
	]);

view raw TrackResource.js hosted with ❤ by GitHub

Notice the use of the extend function to add the behavior in TrackMethods to the prototype of Track resource.

TrackMethods is an object containing several functions that hide the inner structure of the Track resource and make its use more readable:

	app.factory('trackMethods', [
	'ApiKey',
	'measure',
	function (ApiKey, measure) {
	return {
	getUrl: function () {
	return this.resource_uri +
	'?apikey=' + ApiKey;
	},
	getStatisticsValueFor: function (statType) {
	if (this.statisticIsNotDefined(statType)) {
	return 0;
	}
	return measure.getValue(
	statType,
	this.statistics.data[statType]
	);
	},
	statisticIsNotDefined: function (statType) {
	return _.isUndefined(this.statistics) ||
	_.isUndefined(this.statistics.data) ||
	_.isUndefined(this.statistics.data[statType]);
	},
	getStatistics: function () {
	return this.statistics.data;
	},
	getChartFor: function (graphicType, xAxis) {
	return this.graphics.data[graphicType][xAxis];
	},
	getXAxisUnits: function (graphicType, currentSelectedXAxis) {
	var xAxisBySelectedXAxis = {
	"with_respect_to_distance": "distance",
	"with_respect_to_time": "time"
	},
	xAxis = xAxisBySelectedXAxis[currentSelectedXAxis];
	return this.graphics.data[graphicType]["units"][xAxis];
	},
	getYAxisUnits: function (graphicType) {
	var yAxisByGraphicType = {
	"speed_graphics": "speed",
	"elevations_graphics": "elevation",
	"cadence_graphics": "cadence",
	"heart_rate_graphics": "heart_rate"
	},
	yAxis = yAxisByGraphicType[graphicType];
	return this.graphics.data[graphicType]["units"][yAxis];
	},
	getChartsKeys: function () {
	return _.keys(this.graphics.data);
	}
	};
	}
	]);

view raw TrackMethods.js hosted with ❤ by GitHub

The only restriction we put ourselves is that behavior extensions like TrackMethods can't have any state.

Currently TrackMethods contains only accessors, but it will surely grow as the application evolves. All the functions in TrackMethods were discovered in other parts of the code and moved into it. We try to stay alert at new opportunities to attract more code into these behavior extensions.

Another advantage we've found is that these behavior extensions can be easily tested using fake resources.

These are TrackMethods current tests:

	"use strict";
	describe("trackMethods factory", function () {
	var trackMethods;
	beforeEach(module("agora"));
	beforeEach(function () {
	module(function ($provide) {
	$provide.value('ApiKey', "fakeApiKey");
	})
	});
	beforeEach(inject(function (_trackMethods_) {
	trackMethods = _trackMethods_;
	}));
	describe("added behavior to get information about Track file URL", function () {
	it("adds behavior to Track in order to get the Url needed to get the Track file",
	inject(function (ApiKey) {
	var fakeTrack = {
	resource_uri: "a_track_resource_uri"
	};
	_.extend(fakeTrack, trackMethods);
	expect(fakeTrack.getUrl())
	.toBe("a_track_resource_uri" + '?apikey=' + ApiKey);
	})
	);
	});
	describe("added behavior to get information about statistics", function () {
	var statisticsData = {
	distance: {
	val: 12.9,
	unit: "km"
	},
	duration: {
	val: 20.5,
	unit: "min"
	}
	},
	fakeTrackWithStatistics = {
	statistics: {
	data: {
	distance: {
	val: 12.9,
	unit: "km"
	},
	duration: {
	val: 20.5,
	unit: "min"
	}
	}
	}
	};
	it("adds behavior to Track in order to get the value of a given statistics type from the Track", function () {
	_.extend(fakeTrackWithStatistics, trackMethods);
	expect(fakeTrackWithStatistics.getStatisticsValueFor('distance'))
	.toBe('12.90');
	expect(fakeTrackWithStatistics.getStatisticsValueFor('duration'))
	.toBe('00:20:30');
	});
	it("adds behavior to Track in order to get the statistics from the Track", function () {
	_.extend(fakeTrackWithStatistics, trackMethods);
	expect(fakeTrackWithStatistics.getStatistics())
	.toEqual(statisticsData);
	});
	});
	describe("added behavior to get information about charts", function () {
	var fakeTrackWithCharts;
	beforeEach(function () {
	fakeTrackWithCharts = {
	graphics: {
	data: {
	speed_graphics: {
	units: {
	distance: "km",
	speed: "km/h",
	time: "min"
	},
	with_respect_to_distance: [
	[0, 84.347023678293046],
	[0.00759832001978291, 78.967678756],
	[0.0199020023655221, 70.5676347023]
	],
	with_respect_to_time: [
	[0, 84.347023678293046],
	[0.25, 78.967678756],
	[0.43333333333333, 70.5676347023]
	]
	},
	elevations_graphics: {
	units: {
	distance: "km",
	elevation: "m",
	time: "min"
	},
	with_respect_to_distance: [
	[0, 0],
	[0.00759832001978291, 2.3235974923137],
	[0.0199020023655221, 4.0266596767875]
	],
	with_respect_to_time: [
	[0, 0],
	[0.25, 2.3235974923137],
	[0.43333333333333, 4.0266596767875]
	]
	}
	}
	}
	};
	});
	it("adds behavior to Track in order to get the data of a specific chart from the Track", function () {
	_.extend(fakeTrackWithCharts, trackMethods);
	expect(fakeTrackWithCharts.getChartFor('elevations_graphics', 'with_respect_to_distance'))
	.toEqual([
	[0, 0],
	[0.00759832001978291, 2.3235974923137],
	[0.0199020023655221, 4.0266596767875]
	]);
	});
	it("adds behavior to Track in order to get the units of a specific axis of a chart from the Track", function () {
	fakeTrackWithCharts.graphics.data.speed_graphics.units.distance = "m";
	fakeTrackWithCharts.graphics.data.speed_graphics.units.time = "hour";
	fakeTrackWithCharts.graphics.data['cadence_graphics'] = {
	units: {distance: 'km', cadence: 'rpm', time: 'min'}
	};
	fakeTrackWithCharts.graphics.data['heart_rate_graphics'] = {
	'units': {distance: 'km', heart_rate: 'bpm', time: 'min'}
	};
	_.extend(fakeTrackWithCharts, trackMethods);
	expect(fakeTrackWithCharts.getXAxisUnits('elevations_graphics', 'with_respect_to_distance'))
	.toEqual("km");
	expect(fakeTrackWithCharts.getXAxisUnits('elevations_graphics', 'with_respect_to_time'))
	.toEqual("min");
	expect(fakeTrackWithCharts.getXAxisUnits('speed_graphics', 'with_respect_to_distance'))
	.toEqual("m");
	expect(fakeTrackWithCharts.getXAxisUnits('speed_graphics', 'with_respect_to_time'))
	.toEqual("hour");
	expect(fakeTrackWithCharts.getYAxisUnits('elevations_graphics'))
	.toEqual("m");
	expect(fakeTrackWithCharts.getYAxisUnits('speed_graphics'))
	.toEqual("km/h");
	expect(fakeTrackWithCharts.getYAxisUnits('cadence_graphics'))
	.toEqual("rpm");
	expect(fakeTrackWithCharts.getYAxisUnits('heart_rate_graphics'))
	.toEqual("bpm");
	});
	it("adds behavior to Track in order to get the list of chart keys (types of charts, e.g., elevations_graphics, speed_graphics) " +
	"that the Track contains", function () {
	jasmine.addMatchers({toEqualIgnoringOrder: toEqualIgnoringOrder});
	_.extend(fakeTrackWithCharts, trackMethods);
	expect(fakeTrackWithCharts.getChartsKeys()).toEqualIgnoringOrder(["elevations_graphics", "speed_graphics"]);
	});
	});
	function toEqualIgnoringOrder() {
	return {
	compare: function (actual, expected) {
	var actualCopy, expectedCopy;
	if (actual.length !== expected.length) {
	return {
	pass: false
	};
	}
	actualCopy = actual.slice(0);
	expectedCopy = expected.slice(0);
	actualCopy.sort();
	expectedCopy.sort();
	return {
	pass: _.isEmpty(_.difference(actualCopy, expectedCopy)) &&
	_.isEmpty(_.difference(expectedCopy, actualCopy))
	};
	}
	};
	}
	});

view raw TrackMethodsSpec.js hosted with ❤ by GitHub

This strategy of extending Angular resources with behavior is an alternative to encapsulate collection which is working quite well for us to avoid primitive-obsession-related problems.

Interesting Paper: "Out of the tar pit"

I've just read this very interesting paper by Ben Moseley & Peter Marks presenting Functional Relational Programming (FRP):

• Out of the tar pit

Interesting Talk: "TDD by example"

I've just watched this great live-demo of using TDD to code a UI by Toran Billups:

• TDD by example

Interesting Talk: "Stop Treading Water: Learning to Learn"

I've just watched this interesting talk by Edward Kmett:

• Stop Treading Water: Learning to Learn

Mars Rover using a finite state machine implemented with mutually recursive functions and trampoline

I've continued working on the Mars Rover kata.

This time I've solved it using a finite state machine implemented with mutually recursive functions and trampoline.

Mutually recursive functions are a nice functional way to implement finite state machines and it's a functional way of expressing the state pattern (see Functional Programming Patterns in Scala and Clojure, Michael Bevilacqua-Linn).

As in the previous example using protocols, we have four possible states of the rover:

• The rover is facing north
• The rover is facing east
• The rover is facing south
• The rover is facing west

and we have four valid transitions from each state:

• Rotate left
• Rotate right
• Move forwards
• Move backwards

which correspond to the commands that the rover can receive.

These states and transitions can be directly translated to a set of mutually recursive functions by associating each state to a function:

• The rover is facing north -> facing-north
• The rover is facing east -> facing-east
• The rover is facing south -> facing-south
• The rover is facing west -> facing-west

and each transition as a condition to call the next function.

This is the new code of the rover name space:

	(ns mars-rover.rover
	(:require [mars-rover.worlds :refer [rover-not-hitting-obstacle wrap]]))
	(defn rover [x y direction]
	{:x x :y y :direction direction})
	(defn process [commands {direction :direction :as initial-rover} world]
	(let [wrap-rover (partial wrap world)]
	(letfn
	[(facing-north
	[{:keys [x y] :as current-rover} [command & rest-commands]]
	#(if command
	(case command
	:rotate-right
	(facing-east (rover x y :east) rest-commands)
	:rotate-left
	(facing-west (rover x y :west) rest-commands)
	:move-forwards
	(facing-north
	(rover-not-hitting-obstacle
	current-rover
	(wrap-rover (rover x (inc y) :north))
	world)
	rest-commands)
	:move-backwards
	(facing-north
	(rover-not-hitting-obstacle
	current-rover
	(wrap-rover (rover x (dec y) :north))
	world)
	rest-commands))
	current-rover))
	(facing-south
	[{:keys [x y] :as current-rover} [command & rest-commands]]
	#(if command
	(case command
	:rotate-right
	(facing-west (rover x y :west) rest-commands)
	:rotate-left
	(facing-east (rover x y :east) rest-commands)
	:move-forwards
	(facing-south
	(rover-not-hitting-obstacle
	current-rover
	(wrap-rover (rover x (dec y) :south))
	world)
	rest-commands)
	:move-backwards
	(facing-south
	(rover-not-hitting-obstacle
	current-rover
	(wrap-rover (rover x (inc y) :south))
	world)
	rest-commands))
	current-rover))
	(facing-east
	[{:keys [x y] :as current-rover} [command & rest-commands]]
	#(if command
	(case command
	:rotate-right
	(facing-south (rover x y :south) rest-commands)
	:rotate-left
	(facing-north (rover x y :north) rest-commands)
	:move-forwards
	(facing-east
	(rover-not-hitting-obstacle
	current-rover
	(wrap-rover (rover (inc x) y :east))
	world)
	rest-commands)
	:move-backwards
	(facing-east
	(rover-not-hitting-obstacle
	current-rover
	(wrap-rover (rover (dec x) y :east))
	world)
	rest-commands))
	current-rover))
	(facing-west
	[{:keys [x y] :as current-rover} [command & rest-commands]]
	#(if command
	(case command
	:rotate-right
	(facing-north (rover x y :north) rest-commands)
	:rotate-left
	(facing-south (rover x y :south) rest-commands)
	:move-forwards
	(facing-west
	(rover-not-hitting-obstacle
	current-rover
	(wrap-rover (rover (dec x) y :west))
	world)
	rest-commands)
	:move-backwards
	(facing-west
	(rover-not-hitting-obstacle
	current-rover
	(wrap-rover (rover (inc x) y :west))
	world)
	rest-commands))
	current-rover))
	(initial-state-fn
	[direction]
	(case direction
	:north facing-north
	:south facing-south
	:east facing-east
	:west facing-west))]
	(trampoline (initial-state-fn direction)
	initial-rover
	commands))))

view raw rover-FSA.clj hosted with ❤ by GitHub

Notice how inside each of the functions representing rover states (facing-north, facing-east, facing-south and facing-west), there is a case on the command which determines which of the functions will be called next, i. e., which is the next rover state.

Once the next function is selected, we pass it the rest of the commands (notice how destructuring is used to succinctly extract the first command and the rest of commands).

The recursion ends when there are no more commands (command will evaluate to nil), in which case we return the current-rover.

Ok, now some technical details:

1. Trampoline function. The trampoline function is used in order to make Clojure optimize the mutual recursion.
   Each state function returns a function returning a value (notice the # tacked onto the front of the outer level of each state function) instead of directly returning the value. This is required by the trampoline function so it can manage the stack on the mutually recursive calls to avoid stack consumption for long command sequences.
   To start the trampoline we feed it with the initial state function (given by get-initial-state-fn) and its parameters.
2. letfn form. Using letfn allows to create local functions which can refer to each other. This can't be done using let because it executes its bindings serially.

The rest of the name spaces have changed also a bit.

The commands name space now just translates from the received character signals to keywords representing each command:

	(ns mars-rover.commands)
	(def commands-by-message
	{"r" :rotate-right
	"l" :rotate-left
	"f" :move-forwards
	"b" :move-backwards})
	(defn create-from [messages]
	(map #(commands-by-message (str %)) messages))

view raw rover.commands-FSA.clj hosted with ❤ by GitHub

The worlds name space is nearly the same, I just added two helpers (wrap and rover-not-hitting-obstacle) so that the functions that do the wrapping and the collisions with obstacles checking are easier to use in rover name space (they also help to hide the inner structure of worlds):

	(ns mars-rover.worlds)
	(defn square-world [x y size & obstacles]
	{:wrap-fn
	(fn [{x-rover :x y-rover :y :as rover}]
	(cond
	(and (> y-rover y)
	(> (- y-rover y) size))
	(assoc-in rover [:y] (- y-rover size))
	(and (< y-rover y)
	(< (- y y-rover) size))
	(assoc-in rover [:y] (+ y-rover size))
	(and (> x-rover x)
	(> (- x-rover x) size))
	(assoc-in rover [:x] (- x-rover size))
	(and (< x-rover x)
	(< (- x x-rover) size))
	(assoc-in rover [:x] (+ x-rover size))
	:else rover))
	:obstacles obstacles})
	(def infinite-world
	{:wrap-fn identity
	:obstacles []})
	(defn hit-obstacle? [{x-rover :x y-rover :y} obstacles]
	(= (some #{{:x x-rover :y y-rover}} obstacles)
	{:x x-rover :y y-rover}))
	(defn wrap [world rover]
	((:wrap-fn world) rover))
	(defn rover-not-hitting-obstacle [current-rover next-rover {obstacles :obstacles}]
	(if (hit-obstacle? next-rover obstacles)
	current-rover
	next-rover))

view raw rover-worlds-FSA.clj hosted with ❤ by GitHub

Finally, the core name space is much simpler now:

	(ns mars-rover.core
	(:require [mars-rover.commands :as commands]
	[mars-rover.worlds :refer [infinite-world hit-obstacle?]]
	[mars-rover.rover :as rover]))
	(defn- validate-initial-position [rover {obstacles :obstacles}]
	(when (hit-obstacle? rover obstacles)
	(throw (IllegalArgumentException.
	"Initial position is on an obstacle!"))))
	(defn receive [rover messages & {world :world :or {world infinite-world}}]
	(validate-initial-position rover world)
	(rover/process (commands/create-from messages) rover world))

view raw rover-core-FSA.clj hosted with ❤ by GitHub

I'm using exactly the same tests I used in the three previous solutions:

1. Kata: Mars Rover in Clojure using multimethods
2. Separating Mars Rover code into different name spaces
3. Mars Rover code version using protocols instead of multimethods

so I won't post them again.

You can find the code of this last example in this GitHub repository.

I've discovered this other way of doing this in these two great books:

• The Joy of Clojure, Second Edition by Michael Fogus and Chris Houser which I'm enjoying reading at the moment and from which I've got many of the explanations in this post. I'm learning a lot with it.
• Functional Programming Patterns in Scala and Clojure by Michael Bevilacqua-Linn which is a great book from which you can learn how to express many design pattens in a functional (and most of the times much simpler) way.

I've learned a lot coding this solution.

Interesting Talk: "REST in peace"

I've just watched this interesting talk by Martín Salías (in Spanish):

• REST in peace

Interesting Talk: "Are We There Yet?"

I've just watched this great talk by Rich Hickey:

• Are We There Yet?

Mars Rover code version using protocols instead of multimethods

I've continued working on the Mars Rovers kata code that I first implemented using multimethods.

In this version I've used protocols instead of multimethods.

Since I had previously distributed the code in several different name spaces, I only had to modify the rover name space.

The rest of the code keeps just using the same functions of the rover name space: the rover factory and the four commands rotate-left, rotate-right, move-forwards and move-backwards.

However, the implementation of the rover name space is quite different now.

This is the new code:

	(ns mars-rover.rover)
	(defn rover [x y direction]
	{:x x :y y :direction direction})
	(defprotocol Rotable
	(rotate-left [this])
	(rotate-right [this]))
	(defprotocol Movable
	(move-forwards [this])
	(move-backwards [this]))
	(defrecord FacingNorth [x y]
	Rotable
	(rotate-left
	[{:keys [x y]}]
	(rover x y :west))
	(rotate-right
	[{:keys [x y]}]
	(rover x y :east))
	Movable
	(move-forwards
	[{:keys [x y]}]
	(rover x (inc y) :north))
	(move-backwards
	[{:keys [x y]}]
	(rover x (dec y) :north)))
	(defrecord FacingSouth [x y]
	Rotable
	(rotate-left
	[{:keys [x y]}]
	(rover x y :east))
	(rotate-right
	[{:keys [x y]}]
	(rover x y :west))
	Movable
	(move-forwards
	[{:keys [x y]}]
	(rover x (dec y) :south))
	(move-backwards
	[{:keys [x y]}]
	(rover x (inc y) :south)))
	(defrecord FacingEast [x y]
	Rotable
	(rotate-left
	[{:keys [x y]}]
	(rover x y :north))
	(rotate-right
	[{:keys [x y]}]
	(rover x y :south))
	Movable
	(move-forwards
	[{:keys [x y]}]
	(rover (inc x) y :east))
	(move-backwards
	[{:keys [x y]}]
	(rover (dec x) y :east)))
	(defrecord FacingWest [x y]
	Rotable
	(rotate-left
	[{:keys [x y]}]
	(rover x y :south))
	(rotate-right
	[{:keys [x y]}]
	(rover x y :north))
	Movable
	(move-forwards
	[{:keys [x y]}]
	(rover (dec x) y :west))
	(move-backwards
	[{:keys [x y]}]
	(rover (inc x) y :west)))
	(defn oriented-rover [{:keys [x y direction]}]
	(case direction
	:north (FacingNorth. x y)
	:south (FacingSouth. x y)
	:east (FacingEast. x y)
	:west (FacingWest. x y)))
	(defn rotate-left [rover]
	(rotate-left (oriented-rover rover)))
	(defn rotate-right [rover]
	(rotate-right (oriented-rover rover)))
	(defn move-forwards [rover]
	(move-forwards (oriented-rover rover)))
	(defn move-backwards [rover]
	(move-backwards (oriented-rover rover)))

view raw mars-rover-with-protocols.clj hosted with ❤ by GitHub

I've defined two protocols Rotable and Movable which are implemented by new four defined records: FacingNorth, FacingSouth, FacingWest and FacingEast.

Depending on the value of the rover direction, the oriented-rover factory function, creates an instance of one of those records.

When one of the command functions (rotate-left, rotate-right, move-forwards or move-backwards) is called, it calls a function with the same name passing it the result of calling the oriented-rover factory on the rover.
This call is dispatched on the type of the record the call to oriented-rover returns, so that, in the end, the right implementation of the function gets called.

This has been a nice exercise to explore and practice with protocols.

I'll continue exploring other ways to solve this kata with Clojure.

You can find the code in this GitHub repository.

-----------

Update: I continued working in this code on Mars Rover using a finite state machine implemented with mutually recursive functions and trampoline

Separating Mars Rover code into different name spaces

I've separated the Mars Rover kata code I started in a previous post into different namespaces.

This is the new directory structure in which there are three new name spaces: commands, worlds and rover.

mars-rover
├── project.clj
├── README.md
├── src
│   └── mars_rover
│       ├── commands.clj
│       ├── core.clj
│       ├── rover.clj
│       └── worlds.clj
└── test
    └── mars_rover
        └── core_test.clj

view raw mars-rover-tree.md hosted with ❤ by GitHub

The commands name space contains the code in charge of creating the commands from the messages received:

	(ns mars-rover.commands
	(:require [mars-rover.rover :as rover]))
	(def commands-by-message
	{"r" rover/rotate-right
	"l" rover/rotate-left
	"f" rover/move-forwards
	"b" rover/move-backwards})
	(defn create-from [messages]
	(map #(commands-by-message (str %)) messages))

view raw mars-rovers-commands.clj hosted with ❤ by GitHub

The rover name space contains the rover factory function and the command multimethods that are applied on rovers:

	(ns mars-rover.rover)
	(defn rover [x y direction]
	{:x x :y y :direction direction})
	(defmulti rotate-left :direction)
	(defmethod rotate-left :north [{x :x y :y}]
	(rover x y :west))
	(defmethod rotate-left :south [{x :x y :y}]
	(rover x y :east))
	(defmethod rotate-left :east [{x :x y :y}]
	(rover x y :north))
	(defmethod rotate-left :west [{x :x y :y}]
	(rover x y :south))
	(defmulti rotate-right :direction)
	(defmethod rotate-right :north [{x :x y :y}]
	(rover x y :east))
	(defmethod rotate-right :south [{x :x y :y}]
	(rover x y :west))
	(defmethod rotate-right :east [{x :x y :y}]
	(rover x y :south))
	(defmethod rotate-right :west [{x :x y :y}]
	(rover x y :north))
	(defmulti move-forwards :direction)
	(defmethod move-forwards :north [{x :x y :y direction :direction}]
	(rover x (inc y) direction))
	(defmethod move-forwards :south [{x :x y :y direction :direction}]
	(rover x (dec y) direction))
	(defmethod move-forwards :east [{x :x y :y direction :direction}]
	(rover (inc x) y direction))
	(defmethod move-forwards :west [{x :x y :y direction :direction}]
	(rover (dec x) y direction))
	(defmulti move-backwards :direction)
	(defmethod move-backwards :north [{x :x y :y direction :direction}]
	(rover x (dec y) direction))
	(defmethod move-backwards :south [{x :x y :y direction :direction}]
	(rover x (inc y) direction))
	(defmethod move-backwards :east [{x :x y :y direction :direction}]
	(rover (dec x) y direction))
	(defmethod move-backwards :west [{x :x y :y direction :direction}]
	(rover (inc x) y direction))

view raw mars-rover-rover.clj hosted with ❤ by GitHub

and the worlds name space contains the code related to wrapping rovers in a world and detecting obstacles:

	(ns mars-rover.worlds)
	(defn square-world [x y size & obstacles]
	{:wrap-fn
	(fn [{x-rover :x y-rover :y :as rover}]
	(cond
	(and (> y-rover y)
	(> (- y-rover y) size))
	(assoc-in rover [:y] (- y-rover size))
	(and (< y-rover y)
	(< (- y y-rover) size))
	(assoc-in rover [:y] (+ y-rover size))
	(and (> x-rover x)
	(> (- x-rover x) size))
	(assoc-in rover [:x] (- x-rover size))
	(and (< x-rover x)
	(< (- x x-rover) size))
	(assoc-in rover [:x] (+ x-rover size))
	:else rover))
	:obstacles obstacles})
	(def infinite-world
	{:wrap-fn identity
	:obstacles []})
	(defn hit-obstacle? [{x-rover :x y-rover :y} obstacles]
	(= (some #{{:x x-rover :y y-rover}} obstacles)
	{:x x-rover :y y-rover}))

view raw mars-rover-worlds.clj hosted with ❤ by GitHub

I also simplified the application of commands to the rover in the core name space by using a closure so that the apply-command function captures the world instead of passing it in the reduce accumulator as I was doing before:

	(ns mars-rover.core
	(:require [mars-rover.commands :as commands]
	[mars-rover.worlds :refer (infinite-world hit-obstacle?)]))
	(defn- make-apply-command [world]
	(fn apply-command [rover command]
	(let [new-rover ((world :wrap-fn) (command rover))]
	(if (hit-obstacle? new-rover (world :obstacles))
	rover
	new-rover))))
	(defn- validate-initial-position [rover {obstacles :obstacles}]
	(when (hit-obstacle? rover obstacles)
	(throw (IllegalArgumentException.
	"Initial position is on an obstacle!"))))
	(defn receive [rover messages & {world :world :or {world infinite-world}}]
	(let [apply-command (make-apply-command world)]
	(validate-initial-position rover world)
	(reduce apply-command
	rover
	(commands/create-from messages))))

view raw mars-rover-core.clj hosted with ❤ by GitHub

I also learned how to use :refer to require only specific symbols from a name space. I'm also using it in the tests (which except for that are exactly as in the previous version of the code).

I think the code has a better structure now.

You can find the code in this GitHub repository.

-----------

Update: I continued working in this code on Mars Rover code version using protocols instead of multimethods and Mars Rover using a finite state machine implemented with mutually recursive functions and trampoline

Kata: Mars Rover in Clojure using multimethods

Yesterday we had a coding dojo in Clojure Developers Barcelona meetup.

We practiced together doing the Mars Rover kata.

I had already done this kata in Java and C++ before (several times) using the state pattern to eliminate all the conditionals on the rover direction and the command pattern to decouple the translation from the messages sent to the rover into commands acting on it.

As usual I used a mix of TDD and work on the REPL to code this Clojure version.

To document the process I committed the code after every passing test and every refactoring and also committed the REPL history. You can find the commits step by step here.

After making the rover rotations work I had a huge cond on the rover direction with an if branching on the command value inside each case.

It was time to refactor.

The suggestion in the kata was to try to eliminate conditionals using maps, multimethods and/or protocols.

First, I used multimethods, dispatching on the rover direction and the message it was receiving just to see how multimethods work.

It took me a while to make it work because I had a error in the arity of a defmethod and the stack trace was difficult for me to understand.

Then I realized that it was much better to separate the translation of messages into commands from the commands themselves. To do it I used a map that associate each message to the command multimethod:

	(def commands-by-message
	{"r" rotate-right
	"l" rotate-left
	"f" move-forwards
	"b" move-backwards})

view raw commands-by-message.clj hosted with ❤ by GitHub

Here you can see one of the multimethods:

	(defmulti rotate-left :direction)
	(defmethod rotate-left :north [{x :x y :y}]
	(rover x y :west))
	(defmethod rotate-left :south [{x :x y :y}]
	(rover x y :east))
	(defmethod rotate-left :east [{x :x y :y}]
	(rover x y :north))
	(defmethod rotate-left :west [{x :x y :y}]
	(rover x y :south))

view raw rotate-left-multi.clj hosted with ❤ by GitHub

From here on, coding the remaining commands using TDD was very easy. I just had to write a failing test and then make it pass by implementing its corresponding defmethod.

Once all the possible commands were working, I started with the functionality of wrapping the rover in a world.

If you check the commits, you'll see that I tried several approaches here because I wasn't sure how to model the world.

In the end, I decided to model the world as a map with a :wrap-fn key associated to the wrap function for a given kind of world. I passed the world map as a keyword parameter to the receive function which had a default value equal to infinite-world whose :wrap-fn was the identity function. That way all my previous tests continue to work without having to change them.

Then I started doing TDD to code the wrap function for a kind of world called squared-world which was created by a factory function by the same name.

Finally, I started with the obstacles which were modeled as a list of positions (which were represented by maps like {:x 1 :y 2}) associated to the :obstacles key in the world map.

To code the hit-obstacle? function I used the REPL for the first time (you can check all my tests on the REPL history which I also committed) to try to make it work using the some function.

After that I just added a validation to check if the initial position of the rover was on an obstacle.

These are the resulting tests using Midje:

	(ns mars-rover.core-test
	(:use midje.sweet)
	(:use [mars-rover.core]))
	(facts
	"about mars rover"
	(facts
	"rotations"
	(facts
	"when facing north"
	(fact
	"it turns right"
	(receive
	(rover 0 0 :north)
	"r") => (rover 0 0 :east))
	(fact
	"it turns left"
	(receive
	(rover 0 0 :north)
	"l") => (rover 0 0 :west)))
	(facts
	"when facing south"
	(fact
	"it turns right"
	(receive
	(rover 0 0 :south)
	"r") => (rover 0 0 :west))
	(fact
	"it turns left"
	(receive
	(rover 0 0 :south)
	"l") => (rover 0 0 :east)))
	(facts
	"when facing east"
	(fact
	"it turns right"
	(receive
	(rover 0 0 :east)
	"r") => (rover 0 0 :south))
	(fact
	"it turns left"
	(receive
	(rover 0 0 :east)
	"l") => (rover 0 0 :north)))
	(facts
	"when facing west"
	(fact
	"it turns right"
	(receive
	(rover 0 0 :west)
	"r") => (rover 0 0 :north))
	(fact
	"it turns left"
	(receive
	(rover 0 0 :west)
	"l") => (rover 0 0 :south))))
	(facts
	"movements"
	(facts
	"when facing north"
	(fact
	"it moves forwards"
	(receive
	(rover 0 0 :north)
	"f") => (rover 0 1 :north))
	(fact
	"it moves backwards"
	(receive
	(rover 0 0 :north)
	"b") => (rover 0 -1 :north)))
	(facts
	"when facing south"
	(fact
	"it moves forwards"
	(receive
	(rover 0 0 :south)
	"f") => (rover 0 -1 :south))
	(fact
	"it moves backwards"
	(receive
	(rover 0 0 :south)
	"b") => (rover 0 1 :south)))
	(facts
	"when facing east"
	(fact
	"it moves forwards"
	(receive
	(rover 0 0 :east)
	"f") => (rover 1 0 :east))
	(fact
	"it moves backwards"
	(receive
	(rover 0 0 :east)
	"b") => (rover -1 0 :east)))
	(facts
	"when facing west"
	(fact
	"it moves forwards"
	(receive
	(rover 0 0 :west)
	"f") => (rover -1 0 :west))
	(fact
	"it moves backwards"
	(receive
	(rover 0 0 :west)
	"b") => (rover 1 0 :west))))
	(fact
	"it can receive several messages"
	(receive
	(rover 0 0 :north)
	"brfflbrbrff") => (rover 1 -4 :south))
	(facts
	"being wrapped into a world"
	(let [world (square-world 1 1 2)]
	(receive
	(rover 1 3 :north)
	"f"
	:world world) => (rover 1 2 :north)
	(receive
	(rover 1 1 :south)
	"f"
	:world world) => (rover 1 2 :south)
	(receive
	(rover 3 1 :east)
	"f"
	:world world) => (rover 2 1 :east)
	(receive
	(rover 1 1 :west)
	"f"
	:world world) => (rover 2 1 :west)))
	(facts
	"hitting obstacles"
	(let [world (square-world 1 1 2 {:x 2 :y 2} {:x 2 :y 1})]
	(receive
	(rover 1 2 :east)
	"f"
	:world world) => (rover 1 2 :east)
	(receive
	(rover 1 2 :east)
	"lfrf"
	:world world) => (rover 2 3 :east)
	(receive
	(rover 1 2 :east)
	"lfrfrf"
	:world world) => (rover 2 3 :south)
	(fact
	"initial position not being on an obstacle"
	(receive
	(rover 2 2 :east) "f":world world)
	=> (throws IllegalArgumentException
	"Initial position is on an obstacle!")))))

view raw mars-rover-test.clj hosted with ❤ by GitHub

and this is the resulting code:

	(ns mars-rover.core)
	(defn rover [x y direction]
	{:x x :y y :direction direction})
	(defn square-world [x y size & obstacles]
	{:wrap-fn (fn [{x-rover :x y-rover :y :as rover}]
	(cond
	(and (> y-rover y)
	(> (- y-rover y) size))
	(assoc-in rover [:y] (- y-rover size))
	(and (< y-rover y)
	(< (- y y-rover) size))
	(assoc-in rover [:y] (+ y-rover size))
	(and (> x-rover x)
	(> (- x-rover x) size))
	(assoc-in rover [:x] (- x-rover size))
	(and (< x-rover x)
	(< (- x x-rover) size))
	(assoc-in rover [:x] (+ x-rover size))
	:else rover))
	:obstacles obstacles})
	(def infinite-world
	{:wrap-fn identity
	:obstacles []})
	(defmulti rotate-left :direction)
	(defmethod rotate-left :north [{x :x y :y}]
	(rover x y :west))
	(defmethod rotate-left :south [{x :x y :y}]
	(rover x y :east))
	(defmethod rotate-left :east [{x :x y :y}]
	(rover x y :north))
	(defmethod rotate-left :west [{x :x y :y}]
	(rover x y :south))
	(defmulti rotate-right :direction)
	(defmethod rotate-right :north [{x :x y :y}]
	(rover x y :east))
	(defmethod rotate-right :south [{x :x y :y}]
	(rover x y :west))
	(defmethod rotate-right :east [{x :x y :y}]
	(rover x y :south))
	(defmethod rotate-right :west [{x :x y :y}]
	(rover x y :north))
	(defmulti move-forwards :direction)
	(defmethod move-forwards :north [{x :x y :y direction :direction}]
	(rover x (inc y) direction))
	(defmethod move-forwards :south [{x :x y :y direction :direction}]
	(rover x (dec y) direction))
	(defmethod move-forwards :east [{x :x y :y direction :direction}]
	(rover (inc x) y direction))
	(defmethod move-forwards :west [{x :x y :y direction :direction}]
	(rover (dec x) y direction))
	(defmulti move-backwards :direction)
	(defmethod move-backwards :north [{x :x y :y direction :direction}]
	(rover x (dec y) direction))
	(defmethod move-backwards :south [{x :x y :y direction :direction}]
	(rover x (inc y) direction))
	(defmethod move-backwards :east [{x :x y :y direction :direction}]
	(rover (dec x) y direction))
	(defmethod move-backwards :west [{x :x y :y direction :direction}]
	(rover (inc x) y direction))
	(def commands-by-message
	{"r" rotate-right
	"l" rotate-left
	"f" move-forwards
	"b" move-backwards})
	(defn create-commands-from [messages]
	(map #(commands-by-message (str %)) messages))
	(defn hit-obstacle? [{x-rover :x y-rover :y} obstacles]
	(= (some #{{:x x-rover :y y-rover}} obstacles) {:x x-rover :y y-rover}))
	(defn apply-command
	[[rover {obstacles :obstacles wrap :wrap-fn :as world} :as rover-and-world] command]
	(let [new-rover (wrap (command rover))]
	(if (hit-obstacle? new-rover obstacles)
	rover-and-world
	[new-rover world])))
	(defn validate-initial-position [rover {obstacles :obstacles}]
	(when (hit-obstacle? rover obstacles)
	(throw (IllegalArgumentException.
	"Initial position is on an obstacle!"))))
	(defn apply-commands [rover world commands]
	(first (reduce apply-command [rover world] commands)))
	(defn receive
	[rover messages & {world :world :or {world infinite-world}}]
	(validate-initial-position rover world)
	(apply-commands rover world (create-commands-from messages)))

view raw mars-rover.clj hosted with ❤ by GitHub

I'm not sure if this is a good factorization for this problem in Clojure, (I feel that what I did for having different implementations of the wrap function is still a bit OO-ish), but it was a good exercise to practice with multimethods and start exploring their possibilities.

You can find the code in this GitHub repository.

Next time I'll try doing the same exercise using protocols instead.

I enjoyed a lot this coding dojo.

Thanks everyone for coming and Akamon for letting us use its facilities.

-----------

Update: I continued working in this code on Separating Mars Rover code into different name spaces, Mars Rover code version using protocols instead of multimethods and Mars Rover using a finite state machine implemented with mutually recursive functions and trampoline