The Pyramid of Code Quality

When evaluating the quality of code, I consider three criteria, whereby each must be satisfied before considering the next. I’ve put these levels into pyramid that I’ve dubbed “The Pyramid of Code Quaity” aka “The 3 C’s” aka “Code’s Hierarchy of Needs”:

image

Correctness

It should go without saying that if the code doesn’t do what it’s intended to do, it’s worthless (or worse, dangerous). If the code being reviewed doesn’t include tests, then one could even say that the code is not even wrong, since there’s no easy and reproducible way to determine if it works correctly.

Clarity

Once you know that the code is correct and solves the intended problem, it’s important that the code is readable by other programmers. Just because a piece of code works today it does not mean it’s free of bugs, has all the desired features. Plus, software is known to rot over time. Even if the original author remains the sole maintainer, they still need to read and understand the code at some point in the future.

To improve clarity, code should have properly named variables and function, have just enough comments (not too many or too few), use well known design patterns, and follow the given language’s common styles and practices.

Cleverness (aka Conciseness)

Once the code is correct and clearly readable, only then does the cleverness of the code matter. For some programming languages, like Ruby, the cleverness of code is often in service of making it as concise as possible, saving a line here or a character there. Unfortunately, this cleverness can often jeopardize the clarity of the code, in which case it should be avoided.

On the other hand, if you were to compare two equally correct and clearly readable pieces of code, the one more cleverly and concisely written should be preferred. After all, less code produces fewer bugs.

iOS “Open in Chrome” Bookmarklet

Today Google released Chrome for iOS (for free).

Already it’s pretty clear that it’s a much better browser than iOS’s default Safari browser. Unfortunately, even if you want to use Chrome, clicking a link in any other iOS app will launch Safari.

My current workaround is this bit of javascript that will launch the current page in Chrome. Just copy and paste it into a bookmark in Safari, then if you ever find yourself in Safari, but would rather be in Chrome, tap the bookmark and voila! You’re now in Chrome but on the same page!

javascript:location.href="googlechrome"+location.href.substring(4);


Install instructions:

  1. Copy the bit of code up there.
  2. Bookmark this page.
  3. Open the Safari bookmarks, click “edit”, and edit the new bookmark.
  4. Rename it to “Open in Chrome” or something like that.
  5. Delete the URL that’s there and paste in the above code.

How To Use HTML5 pushState

I recently made a simple web app over a weekend called diffbin. It gave me a chance to try out a really cool HTML5 feature called pushState (aka the History API).

While there exist libraries to make it easier to implement, I wanted to code it by hand in order to better understand the feature. It turns out it was much simpler than expected.

To prove how easy it is, and to encourage other developers to try it out, I’ve broken the use of pushState down into 5 easy steps.

Step 1 - Prepare Your Paths

The first step to using pushState is to make sure your app can handle all the URL paths that you create. This should be obvious, and if you wrote your app originally using the page refresh method I mentioned previously, you should be set. On the other hand, if you wrote your app to depend on URL fragments, then you may need to create the necessary request handler to render the requested URL.

Step 2 - Use pushState i.e. Setting The New URL Path

This is the best part: where you get to change the browser’s current address without reloading the page. For diffbin (source), I change the browser’s address when the user clicks the save changes button. The JavaScript code makes a call to the server to store the user’s changes and gets back the new URL path.

Once I have the new path, I simply do this:

The history.pushState() function takes 3 parameters. The first is an object containing the new state of the app. What the state object contains is up to you, your app will need it later (see step 5). The second parameter, as far as I can tell, isn’t currently used by any browser so just leave it null. The third parameter is what you want the new path in the browser to be set to.

You can test out the pushState command on any page you have open, even this one! If you’re in Chrome just open the JavaScript Console and execute:

history.pushState({}, null, “/hello”);

Notice how the address bar changed, neat eh?

Step 3 - Add Legacy Browser Support

Since only modern browsers support this functionality, we need to make sure that older browsers like IE still work. For that we fall back on the clunkier page reload method. Yes, the user’s experience will be diminished, but it’s worth it to improve the experience of users that have modern browsers.

Step 4 - Set Initial State

After calling the history.pushState function you may notice that if you hit back on your browser, the address bar will change, but your content will remain the same. That’s because we need to re-show the old state. But before we can even do that we need to actually store what is in the initial state when you first load the page.

So far, the only way we’ve seen for storing state information is using the pushState function, which doesn’t just change the URL but also adds an entry to the browser’s history.

To set the initial state we use the history.replaceState function. It’s pretty much exactly like pushState, but it doesn’t affect the browser history. So it allows you to store the initial browser state when you first load the page without any side effects.

Note: The third parameter for the replaceState call is null because we’re not changing the current URL, we’re just storing a state object.

Step 5 - Pop The State

So now that each time we load or change the URL we’re storing the state, we can use that state information to update the page when a history event occurs. A history event is when a user hits either the back or forward button in their browser.

To do this, simply assign a function to window.onpopstate, and then access the state object event.state.

Conclusion

That’s the basics to get you started. There’s now no excuse for you to not use this awesome new web browser feature.

If you’d like to learn more, I recommend Mozilla’s excellent documentation on the History API.