Monday, April 13, 2015

Presenting Abstract Feature Branch at Montreal.rb April 2015

I am giving a talk at this month's Montreal.rb user group, taking place next week on April 21, 2015:
http://www.montrealrb.com/2015/04/april-21th-meetup/

Abstract:

How many times do you find yourself near the software release finish line on an exciting new feature only to be pulled off by management in the last minute to sneak in some higher priority emergency fix? What do you do with the unfinished feature's code if parts of it were already functional and merged into master? Do you pluck it out and move to a remote feature branch? Do you simply comment out the code not ready for exposure to the customer? What about some of the nice software design improvements that were done as part of the feature and are being put to good use by the team today? Do you also put design improvements off till the feature is deemed by management high priority again?

These questions typically get decided on by the team on a case by case basis, and often with big compromises affecting both project delivery and code quality.

While consulting for Sears in 2009 and working at Groupon.com in 2012, I happened to work in teams that adopted a very effective and inexpensive solution to the problem called "Branch by Abstraction", a technique originally popularized by Martin Fowler, author of UML Distilled and Patterns of Enterprise Application Architecture.

In this talk, I aim to explain Branch by Abstraction and demonstrate how to apply in Ruby using a gem I wrote called Abstract Feature Branch, partly inspired by the internal team libraries used at Sears and Groupon. The gem has already had over 50,000 downloads from rubygem.org and has been utilized in several of my newer projects, including launch of EarlyShares.com and enhancements of Factor75.com.


Attendees should walk out with basic understanding of Branch by Abstraction and enough knowledge of Abstract Feature Branch to be able to explore further in their own projects after the talk.

Tuesday, April 07, 2015

SuperModule v1.1.0 is the New Sherif in Town!

After posting an article on AirPair.com about SuperModule v1.0.0 and getting quite a bit of feedback on it in the form of article reviews and reddit posts, I decided to make a new revision with quite a number of improvements, which was released yesterday as SuperModule v1.1.0:

What's New in v1.1.0?

  • Brand new self-friendly algorithm that ensures true mixing of super module singleton methods into the including base class or module, thus always returning the actual base class or module self when invoking a super module inherited singleton method (thanks to Banister for reporting previous limitation on Reddit and providing suggestions)
  • New included_super_modules inherited singleton method that provides developer with a list of all included super modules similar to the Ruby included_modules method.
  • No more use for method_missing (Thanks to Marc-AndrĂ© Lafortune, a Ruby language contributor, for bringing up as a previous limitation in AirPair article reviews)
  • New dependency on Banister's method_source library to have the self-friendly algorithm eval inherited class method sources into the including base class or module.
  • Refactorings, including break-up of the original SuperModule into 3 modules in separate files
  • More RSpec test coverage, including additional method definition scenarios, such as when adding dynamically via class_eval and define_method
Cheers...

Thursday, March 27, 2014

Ruby SuperModule Comes To The Rescue!!

Tired of ActiveSupport::Concern and Ruby's modules not allowing you to mix in class methods easily? Well, worry no more! SuperModule comes to the rescue!



SuperModule allows defining class methods and method invocations the same way a super class does without using def included(base).

This succeeds ActiveSupport::Concern by offering lighter purely idiomatic Ruby syntax and simpler module dependency support.

1. Just include SuperModule at the top of a module definition:
module UserIdentifiable
  include SuperModule

  belongs_to :user
  validates :user_id, presence: true

  def self.most_active_user
    User.find_by_id(select('count(id) as head_count, user_id').group('user_id').order('count(id) desc').first.user_id)
  end

  def slug
    "#{self.class.name}_#{user_id}"
  end
end

2. Mix newly defined module into a class or another super module
class ClubParticipation < ActiveRecord::Base
  include UserIdentifiable
end
class CourseEnrollment < ActiveRecord::Base
  include UserIdentifiable
end
module Accountable
  include SuperModule
  include UserIdentifiable
end
class Activity < ActiveRecord::Base
  include Accountable
end

3. And start using by invoking class methods or instance methods
CourseEnrollment.most_active_user
ClubParticipation.most_active_user
Activity.last.slug
ClubParticipation.create(club_id: club.id, user_id: user.id).slug
CourseEnrollment.new(course_id: course.id).valid?

More details and examples are available over here: https://github.com/AndyObtiva/super_module

And the SuperModule RubyGem lives over here: http://rubygems.org/gems/super_module

Enjoy!!

Saturday, March 15, 2014

Presenting at RailsConf 2014

Update: here are the links to the talk video and slides

My talk "Ultra Light and Maintainable Rails Wizards" has been added to the RailsConf 2014 program

Abstract:

Wizards have been common in web applications since the dawn of the Internet, with the most popular example being the Shopping Cart, yet many struggle with writing wizard code effectively, resulting in a huge untraceable rat's nest of copy/paste code. In fact, many implementations violate REST and include Fat Controllers as well as overly complicated wizard-step management, data, session, and validation code. This talk covers a better way that yields Ultra Light and Maintainable Rails Wizards!

If you have any special requests to include in the talk, please let me know in the comments.

Looking forward to connecting with Rails developers at RailsConf 2014.

Monday, February 03, 2014

Ultra Light and Maintainable Rails Wizards at RailsConf and EuRuKo 2014

I have submitted proposals for the following talk at RailsConf 2014 and EuRuKo 2014:

Title: Ultra Light and Maintainable Rails Wizards

Abstract:

Every developer probably struggled at one point with building a large multi-step wizard that spanned several weeks to develop, interrupted by the client multiple times to insert another step here and another step there resulting in big code rewrites or lots of quick copy/paste and code duplication. Developers might address the concern by writing custom code that violates REST, results in Fat Controllers, or includes complicated Wizard step data management code. Andy will introduce a better way!

RailsConf2014 Proposal Link:

If I were to present, I would look forward to meeting you there.


Thursday, October 24, 2013

Ultra Light & Maintainable Wizards in Rails

Recently I worked on Rails applications that had major requirements for web wizards, and they were built incrementally and iteratively with both junior and senior developers contributing further steps to the wizards over the lifetime of the projects. I presented my approach this past summer at the Montreal.rb user group (Update: and RailsConf 2014 ), and I am writing this blog post to provide more details and code examples.


Late last year and early this year when I scoured the net for web wizard approaches in Rails and wizard libraries, I noticed many different variations, happening across many dimensions, like the number of controllers/actions and how data is persisted across wizard pages.

Examples of controller/actions variations:
  • One controller per wizard page
  • One action per wizard page
Examples of Data persistence variations:
  • Save data in the session on every page and create an ActiveRecord when finishing wizard
  • Save data in a different ActiveRecord per wizard page
  • Accumulate data in a hidden field and use on the last step to create an ActiveRecord
  • Save data in one model with the help of a state machine
  • Manage saving data in the controller
Some approaches try to be modular by having multiple controllers or multiple actions. Others try to be light on session use by saving to the database directly.

Here is my personal feedback on the approaches above:
  • A wizard is editing one resource through multiple steps, so why are there multiple actions or controllers involved in building/updating that single resource? That violates REST. Not that it matters to break guidelines except for the pragmatic fact that it makes it more complex for developers and future team members to maintain the code.
  • A single ActiveRecord is being edited across steps even if some steps edit sub-models within it, so saving different ActiveRecords is an over-complication. That violates Cohesiveness by fragmenting the focus of the data persistence of a wizard.
  • Saving data to the session has server scalability concerns and complexity concerns. That makes Scalability harder.
  • Accumulating data in a hidden field increases complexity. That goes against Simple Design.
  • Managing data persistence details in the controller does not divide responsibilities correctly between the controller and model. That violates MVC, making it harder to maintain the code by developers and future team members.
  • A Wizard is simply editing different facets (data views) of a model, and not necessarily moving a model along a Business State Machine. The steps for entering/editing a model are also a View/Presentation concern, so even if a state machine is involved, it is not a model concern. The model might have genuine business states, but are usually only few compared to the steps of the wizard, which might adjust for usability (presentation) reasons, so although there might be overlap between wizard steps and model business states, one must not mix them as that couples the two incorrectly and unnecessarily, complicating maintainability greatly (with much cost to pay by developers over a year). That violates MVC, abuses State Machine, and worsens Maintainability.
So, where does that leave us?

I ended up solving the problem on both Rails projects with a new simple and clean approach following some concrete goals.
Goal Summary
  • Simplicity
  • Maintainability
  • Scalability
  • Proper MVC
  • Proper REST
  • Proper Object Oriented Design (respect for coupling and cohesion principles)
Starting with this end in mind, one way to think about the wizard is that it is nothing but a model builder, akin of the good old Builder Design Pattern. Without a wizard, you usually have one form that a user fills in to create a model. With a wizard, the model is created in multiple steps however, so the REST resource edited in each step is a model part (aka model data view or model step).

Wizard Flow
  • Starting the wizard creates the model and allows the user to edit the first part (data view) of the model
  • Each subsequent step enables the user to edit more parts of the already created model


Guidelines


  • REST: Following REST, the resource is nothing but the good old Model itself, except a wizard focuses on one part of the model at a time, so more accurately "model part" is the RESTful resource for wizards.
  • MVC: Following MVC, each step can be routed to an ActiveRecord representing a part of the Model. To figure out which part, the Controller relies on the ID parameter, indicating the part (step) being edited in addition to model_id. Also, each model part is a subclass of the main Model ActiveRecord to facilitate connection to the database columns with the least code possible while retaining separation of concerns (an improvement would be to use delegation from a wrapper model, useful as a future refactoring step for the design if the coupling to ActiveRecord becomes undesirable later on. In my experience, that has not been an issue, so I elected to rely on single-table-inheritance style of database mapping reuse as you will see below)

With the two guidelines above, the developer has a complete template for the implementation with everything falling into place, and the rest is details. Let's get down and dirty to illustrate the concepts above with code!

Routes ProjectsController is only responsible for creating a project. Afterward, ProjectPartsController manages the project parts as wizard step resources (REST). The routes above will produce this pattern for moving along a wizard (editing a model part): /projects/:project_id/project_parts/:id/edit

ProjectsController
ProjectsController redirects to the first project part (wizard step) after project creation

ProjectPartsController
ProjectPartsController treats model parts (wizard steps) as the resource that can be edited/updated along the way. params[:id] contains the ID of the resource, which is the model part name (aka wizard step name). Rendered views can then match that ID name. The implementation above is one way to do it. The code could be written differently and optimized depending on needs (such as moving some private methods to a Helper and sharing them with the views if needed, like the step and next step for example, which can be displayed visually on the page for labelling and navigation)

Project model
The main project model contains associations and common logic, and then each wizard step can have its own sub-model if necessary to manage step specific validations without having the validations interfere with other steps. Sub-models also manage data loading upon showing the wizard step edit page (via after_initialize) or after updating (via after_save)

Project::BasicInfo sub-model


Project::Detail sub-model

Views

Note how the views match the wizard steps.

View Forms
All view forms (e.g. basic_info.html.erb) will have the form template above, which is agnostic to which model part is being edited. On one project, the developer actually created a helper (e.g. project_part_form_for) that hides all the details and can be unobtrusively reused across all wizard view pages.

Sub-Models

Note how only the wizard steps that require validation logic and special on edit or on update logic need sub-models.

I hope you found this example implementation helpful in your endeavour to implement Ultra Light & Maintainable Wizards in Rails. Note that it is a simpler version of what I have implemented for my clients, which often grew with their rising needs over time, stretching the implementation without much strain due to its simple design and adherence to sound software development guidelines, such as REST and MVC. This approach really scales well since it allows one to add extra authorization checks in the controller without a hitch and extra hooks/validations on the sub-models depending on need. Additionally, it is compatible with the model having a state machine or following the State Design Pattern as implemented on one of my projects.
Now, no write-up would be complete without a Gotchas section, so let's get to that.

Gotchas
  • Validations live in sub-models. What if one wants to have a second mechanism for editing the model in one page utilizing the same validations? Simple. Chop the validations off into Modules, mix each of them into one of the wizard sub-models and then mix them all into a new sub-model to be used as the model for the second editing page. This approach can also be used to reuse validations for the last step of the wizard and re-run all the validations once again at the end if needed.
  • How do you skip a step based on certain rules? You need to build a check into the controller that sees if a certain model part needs to be skipped (via a skip? method for example on the sub-model). If so, the controller simply redirects to the following step. Covering the details of this is outside the scope of the blog post, but I am sure you can figure it out.

On the first project that I added the wizard to, the CTO was happy to see that the junior developer was able to add new steps to the wizard in record time after spending 5 minutes with me going over the details of how it works. On that same project, a senior developer who joined later on and was working remotely figured out the wizard design in no time and sent me congratulations on how flexible and nicely designed it was. The same happened on the other Rails project I used the wizard approach for, which facilitated growing a wizard from about 5 steps to 15 (with some interesting custom logic on step branching). So, you can rest assured this approach will work well and scale for your Rails projects.

Monday, September 16, 2013

First Experience with Rails 4 Turbolinks

Character Business CardMy most recently developed Rails application - CharacterBusinessCard.com - was built with Rails 4, which ships out of the box with a feature called Turbolinks. Here is its description from the Turbolinks github repo:
Turbolinks makes following links in your web application faster. Instead of letting the browser recompile the JavaScript and CSS between each page change, it keeps the current page instance alive and replaces only the body and the title in the head.
In effect, hyperlinks become turbolinks as page loading is perceived to be faster without the reloading of JavaScript and CSS despite having the same network load time for the webpage HTML markup.

In this post, I am sharing some of the gotchas I encountered with this feature, how I dealt with them, and my overall experience with the feature.

Gotchas and Solutions:

1. Style changes were not updating on page navigation

I encountered an issue the first time I tried to leverage the controller-specific CSS stylesheet pattern. For those unfamiliar with the pattern, it is actually about loading an extra CSS file in addition to application.css in order to customize the look of pages belonging to a specific controller. To enable the pattern, one would add a line like the following to their layouts/application.html.erb:

<%= stylesheet_link_tag params[:controller], media: "all" %>

This in effect, loads users.css for the page rendered by users#index or users#show for example.

The benefit of the pattern is simply keeping that CSS maintained separately from other pages so that when the Rails Asset Pipeline builds application.css it does not concatenate many potentially conflicting styles and forcing developers to deal with them with all sorts of complicated hacks. Having a controller-specific CSS loaded per controller page in addition to application.css results in much lighter more maintainable page specific styles.

So, what was the gotcha?

Well, upon updating the controller specific CSS, I noticed that its styles were not reflected when I was navigating between the controller pages until I refreshed the browser page completely. Turns out, that is because I did not have turbolinks tracking enabled, so I had to add this option to resolve the problem: , "data-turbolinks-track" => true, changing the erb to:

<%= stylesheet_link_tag params[:controller], media: "all", "data-turbolinks-track" => true %>

2. On-document-ready JavaScript events were not firing on page navigation

For example, if you have JavaScript code that converts form hints into tooltips like the following code (in CoffeeScript):

$ =>
  $('.hint').tooltip(placement: 'right')

The code above relies on jQuery's shortcut method $ for executing some JavaScript (CoffeeScript) code upon page document load (document ready).

When visiting the form for the first time, the tooltips show up. However, when navigating away to the home page, and navigating back to the form page, the tooltips do not show up anymore.

Turns out that it is expected behavior by Turbolinks' definition. After all, the Turbolinks feature does not reload JavaScript files on page navigation, missing out on the activation of hint tooltips on document load.

Fortunately, the Turbolinks feature offers developers a way to get around this through its own event hooks fired on page navigation. They are detailed in the Turbolinks github repo (highly recommended to visit to learn Turbolinks in depth).

The event hook I used in particular was: "page:load". Using it alone did not resolve the problem however (that worked for page navigation, but not initial page load), so I used it in addition to the original jQuery $ method as follows:

on_load = =>
  $('.hint').tooltip(placement: 'right')

$(on_load)
$(document).on("page:load", on_load)

So in essence, the gotcha fix was to wrap all the page document load logic in a JavaScript function, and then hook it into both on-document-ready (jQuery $) and Turbolinks "page:load"

Experience:

Now regarding my overall experience with Turbolinks, I thought it was a very welcome addition to Rails. It worked quite perfectly once I have gone beyond the two gotchas, resulting in an impressively instant page navigation and making local browser testing much faster and more productive. The JS libraries I have used with Turbolinks by the way are the Spectrum Color Picker, Twitter Bootstrap Tooltips, and Fancybox in addition to usage of JS media queries.

In a way, Turbolinks is the perfect embodiment of the Rails philosophy of discovering common patterns, automating their solutions to be as effortless and friction free as possible for everyone to use, and finally offering the ability to customize or disable all-together. By the way, you can opt out of Turbolinks by adding the attribute "data-no-turbolink" to the HTML body element or divs for which you want links to behave regularly. In essence, Turbolinks' implementation satisfies the 80/20 rule, automating the solution for 80% of the cases (not literally) to increase productivity and allowing developers to customize the solution in the remaining special 20% of the cases (not literally) to allow flexibility. Using Turbolinks is also an instance of following Convention over Configuration.

In conclusion, Turbolinks is like driving your first Porsche. The first couple of times you drive the car, you are out of control and do not know why the hell the car is not behaving like a good old Honda, but then you finally get the hang of it, and suddenly find yourself flying in a 911 Turbo. ;)