Category Archives: Shylock

Code Reviews : The Last Line of Defence

When designing the architecture for a web site, not everything you design is about the technology or the code structure.  Perhaps one of the most important project decisions I think I implemented on “Project Shylock” was to implement mandatory code reviews before commit.

All code commits need to pass a build, run and basic sanity check.

The only times committed files won’t require a code review is for a basic copy text change (and maybe even then) or when development was performed as part of Paired Programming (and maybe even then) or for a binary file.

The benefits for code reviews are plastered all over the internet, but just to re-cap from my own personal experience.

Code Reviews produce the least buggy code

I’m sure there are some metrics out there that may prove TDD (Test Driven Development) makes for the least buggy code, but from my own anecdotal experience, nothing makes for more reliable code than having to go through it line-by-line in front of a peer and having to explain your decisions for each line of code.

Additionally, if you promote a development team where noone codes with ego (another topic!), then critical analysis of code structure and logic will flow naturally.  It can be like getting a free refactor just before you commit your changes.

 Code Reviews cross-pollenate knowledge

When I’m working on code in a team that doesn’t code review, the only time I know what everyone else is doing is during the daily scrum standup… and even then I only get a passing overview of their coding day.

When I’m on a team that is doing code review, I always know what 3 or 4 other people have been working on that week.. to the point that if they are away sick and a bug arises related to it, I generally feel comfortable to jump into the code and try my own hand at it.

Last thoughts…

I went away on vacation for 3 weeks and left my team on an honor system to keep code reviewing themselves.  I was unpleasantly surprised to come back that they had been incredibly overloaded and in their work compression mode, they dropped their code reviews.

It’s an easy thing to do to say “Oh I’m too busy to do this”, but in the end, code reviews only take a few minutes most of the time, and can save HOURS of work… sometimes you don’t have to pay that tech debt until weeks later.. but it will be paid sooner or later.. trust me.

UPDATE: Even Jeff Attwood (of Coding Horror/Stack Overflow fame) agrees!

Creating a Website : Style-First Design

Before we started on Project Shylock, we were very badly burned by an extremely high maintenance web form. When we first started designing it, we made a screen mockup that was pixel-perfect and would dynamically resize its windows according to which panes you toggled open and shut. We created a screen first, then made unique design rules that would allow it to be possible.

It looked beautiful!

Only it wasn’t. It was a hot mess of intertwined javascript resize events that would cascade from parent events down to any dynamic child. A form resize or a toggled pane would trigger the display calculation of up to 10 items. By the time we delivered the form, it worked well and responsively, but the cost of sticking to the pixel-perfect screen layout cost us a few weeks of person-hours.

The Lesson : Style First, the rest will follow

When a graphic designer makes a pixel-perfect layout, there is a less-than-complete understanding of how all the pieces are grouped and how they will all push and pull upon each other.

Know your direction

Work out your fonts, your site’s persona, your flavor.  Make some designs on how you want your site layout, look and feel to flow.

Create your styles

Preferably with something like Sass or Less, lock in a gentle css reset, then start building up your styles. Make css modules of related rules. Typography module, color module, padding, layout, buttons, grids, forms, dialogs…  start with the essentials and expand as you need, but make your rules, work out how it all is going to flow

Communicate your rules to designers

If you are working with designers or graphic design team, communicate your styles and rules.  Make a prototype page with examples of how various objects will interact with each other and let them see and play with them.

When they make designs proposals for new functionality, make them use your rules to make the forms.

The pages will follow the design…

If you stay flexible and Keep It Simple (my mantra!), then when you create your pages, they will start naturally fitting in amongst each other and dictating their own flow.  This works especially well in a web site that has to be dynamic or responsive, because as your controls change or your available space, the controls will adapt as well, with minimal developer intervention.

Pass multiple arguments to console.log from another javascript function

One thing we learned from our last project is that console.log can generate a LOT of noise. This noise is OK from a development environment, but once we move into production, it doesn’t make sense to still be writing to the log… that is until something goes horribly wrong in production and we need it enabled again!

For the record, nothing went horribly wrong in production.

So I devised a small helper class that will show or hide console.log messages depending on how you initialize it. The tricky part is that console.log can take multiple parameters, so I had to use console.log.apply(console, arguments); to relay those parameters untouched.

// logging utility library
function Log(_logConsole) {
	var self = this;
	this.logConsole = true;
	this.log = function() {
		if (self.logConsole) {
			console.log.apply(console, arguments);
		}
	};
	this.init = function () {
		if (_logConsole !== undefined) {
			self.logConsole = _logConsole;
		}
	};
	self.init();
}

And invoke it with:

var jsLog = new Log(true); // write to console
jsLog.log('Loading data', data, this);

Best Practice on “Project Shylock”

Our first sprint began with what I’m going to be calling “Project Shylock” that we are making for *******.

I am leading a passionate team of 3 other UI/UX developers who are all trying to make to best possible website that time will allow. The emphasis is particularly on “time will allow“.

Our organization is now known to us to as a place that will not give us realistic time to complete a project. So at some point, time will run out and we will have to make a decision on whether best practice continues, or we deliver all our required functionality.

Time will tell.

Goals

Our team’s goal for this project is:

  • To deliver code that we will be proud of in two years time
  • To use technology that will help, make sense, not just to look good on a resume
  • To be able to handover completed code that will make sense to a future UI developer who may have to maintain it.

Technology and Methodology

  • Sass style sheets
    1. Sass is fucking cool.
    2. .scss format is backwards compatible with regular .css
    3. Allows us to create style module files
    4. Re-usable variables
    5. Can comment with // (seriously, this may be the best thing about Sass!)
  • NOT using Coffeescript
    1. Harder to handover to a fresh developer
    2. Feels backwards to use a language that turns into another language
  • Mocking data with Mockjax
    1. Mocking allows us to develop without having to wait for the backend Java developers (referred to as Backend or BE) to write a service to connect to
    2. Allows us to give an example to BE to demonstrate the desired data contract
    3. We can re-use the mock in a unit test
  • Object Oriented CSS
    1. All styles are defined by classes.
    2. No objects have their own style. They use a styles from a set of rules to display themselves
    3. Close-to-zero page specific css rules
    4. Style rules dictates page layout, not the other way around
  • Unit testing with QUnit
    1. Will initially be avoiding Test Driven Development, as this approach require heavy pre-planning of design, and our delivery structure doesn’t allow for that.
    2. We will be writing unit tests after our functionality is written
    3. Using Mockjax to simulate AJAX transactions
    4. Unit tests will be reviewed in Code Reviews
    5. We will use an automated test runner to execute our unit tests on a frequent schedule
  • Code Reviews
    1. Code reviews are the best way to improve code quality as well as to cross-train team members of other’s functionality
    2. The only two times a code review won’t be required is for a basic copy text change or when development was performed as part of Paired Programming
    3. Code reviews will include copy text and localization (l10n)
    4. Code reviews will include unit tests
  • Paired Programming
    1. There is no requirement for Paired Programming, but if a developer is unsure of the best way to do something or is having difficulty fixing a problem, then why not grab a buddy and work on it together! It’s fun! 🙂
    2. If you pair program something, then you don’t have to do an additional Code Review!
  • Localization (l10n)
    1. Currently the project users don’t need a second language supported, but it will be used in multiple countries and they cannot 100% rule out that it will ALWAYS be in one language (en-US)
    2. Adding l10n once the project is completed is a special punishment reserved for those who spit gum on the street, play techno in apartments at night, or mistreat animals. If there is a chance it will be needed, we will add it to our project from the ground floor.
    3. l10n libraries will be minimalist to invoke, have helper classes and try and avoid getting in the way of development
    4. Copy Text will be organized into property files based on culture, and internally will be grouped into namespaces
  • Javascript
    1. Using jQuery because it makes everything easy and predictable
    2. All code will be enclosed in function encapsulation
    3. Functions will be broken into logical modules
    4. Common modules will be included in each page with a JSP include, so that when we are ready to combine and gzip them, it will be in one place only
    5. Functions will be written with Injection Dependency in mind. Core functionality will take parameters for UI objects and data, so that they are easier to write unit tests for.
  • Responsive
    1. Using FooTable to handle responsive table layout
    2. Using Sass media directives to handle different viewport sizes
    3. Using a percentage-based grid layout to simplify structure and flow
  • Agile Scrum
    1. Everyone says they are doing Agile Scrum, but we really are.
    2. If it’s not in JIRA, being tracked in our current sprint, then it’s not getting done
    3. Do not maintain your own personal “secret list” of things you have to get done. If you keep that list, be willing to work on that list in your own time on the weekend.
    4. Be transparent, put everything substantial into JIRA as a task so we can see what we can fit into a sprint
    5. All tasks in the current sprint to have story points.
    6. Use story point poker cards or shirt sizes to estimate all projects. Have multiple short rounds of estimates and discussions if you cannot agree initially on points
  • Mustache.js HTML Templating
    1. Our last project we chose the simplicity of Underscore.js to do our templating which gives you ERB style embedding and allows you to embed literal javascript code. This unfortunately allows you to write very messy templates with logic embeded right in them
    2. Mustache allows only template defined control blocks which makes templates easier to read
    3. No-code templates promotes MVC architecture
  • MVC (Model-View-Controller) Application Design
    1. The UI layer is broken into 3 sections, Controllers, Models & Views
    2. Models – Our JSON objects that we receive from our AJAX calls
    3. Controllers – Our javascript classes are our controllers, making ajax calls to retrieve our models. Models that are “too raw” for UI consumption are massaged into more consumable shapes
    4. Views – Using Mustache.js templates, we render business-logic-less localized templates

There is almost certainly more stuff we have decided on, and as I remember them I will add them to this list. Additionally, I will try to report back on what decisions worked, and which ones didn’t. I just hope we have enough time to get it done right.