Markdown: Content Isn’t Just For Web

A couple of my friends and I have the same conversation once or twice a month: How do you deal with content that could be displayed in any number of different devices?

I know, this sounds like chilling lunchtime conversation, but this is what happens when you get a group of programmers together over lunch on the regular. Nonetheless, there is value in this discussion. We don’t all work on the web and we all have to deal with content from the same source.

But, HTML is a known spec.

True, however, the next time you talk to a mobile developer, suggest to them that they process your HTML (and CSS and Javascript and other garbage text) and display it as a part of their native environment. After they laugh long and hearty at you, they are likely to tell you it will never happen.

A friend of mine wrote about the general nature of display agnostic content, and concludes that with the current state of technologies, Markdown is likely the best option for safe cross-platform content. I agree that this is likely true.

First, Markdown is easy to produce. No special editor is even necessary to create a Markdown document since the average person could learn all of the key features in a few minutes. Moreover, for technical users, some key players have adopted a specific dialect known as Github Flavored Markdown (GFM) and there is wide support for it, so converting to and from GFM has become a rather trivial task.

Second, Markdown does not allow for external documents to declare display properties. This means that the display management is left entirely up to the application that is rendering it. Since the user can’t do things like create CSS to make all of the text green and rendered with Comic Sans, the application level control is more sane and normalized. Normalization is a good thing.

Third, Markdown is, at its core, just plain text. Plain text follows rules and standards that can be set outside the scope of your application or organization. If you store the text document in UTF-8 or UTF-16 format, it will always be the same. Everywhere. All of a sudden, you can reason about your document in all kinds of useful ways. You know precisely how big it is. You know exactly how fast it will render. You know, without question, what the format and markers will be.

That’s a really, REALLY big win.

I’m going to sneak a fourth point into my three-point list: Markdown is safe for just about any text format or serialization strategy you can throw at it, because it’s just text.

Markdown in JSON? It’s a string
Markdown in SOAP? It’s a string
Markdown in XML? IT’S A STRING

There are plenty of people out there still using XML. (Don’t laugh, they are out there.) Imagine a world where CDATA just goes away. I mean, capturing XML, parsing it, dealing with CDATA protected strings, making sure everything didn’t get completely borked in the process is a pain in the tuchus. I’ve been there and trust me, it stinks.

Of course this leads us to the inevitable discussion of how we process Markdown. If you are not on the web and you’re relying on any number of different languages to parse and manage Markdown, use Hoedown. Yes, it’s called Hoedown, seriously. Hoedown is a standalone, no libraries needed markdown parser built in C.

It is likely, though, that you are using web technologies to process your Markdown (or you wouldn’t be reading a blog by a JS developer), so I have a special gift for you too: Marked. Marked takes Markdown strings and turns them into standard HTML and it’s easy. Here’s what it looks like when you used marked:

This is great if you already have Markdown and you just need to display it on the web, but what about the output from your favorite WYSIWYG editor? As it turns out, there is a library for that too. To-markdown is a script that will take whatever garbage-formatted HTML comes out of the back end of your HTML editor and turn it into crystal clear Markdown. Here’s what it looks like:

To sum up, if you are working in a multi-platform environment, which is really REALLY common, make friends with your mobile and desktop developers and provide them platform-agnostic content in the form of Markdown. It’s easy to work with, it’s popular, it’s plain text and it’s easy to serialize.

With the solid support of two well-vetted libraries like Marked and To-markdown, there is practically no barrier to entry, so stop saving HTML to the database, and make your content easy to work with. If you drop in the conversion method into the standard content flow in your app, management will just look around one day and notice that everything is a little better and they won’t know why. Who can argue with ‘better,’ really?

Blog Post Notes

Mainstay Monday: Lexical Scoping

Edit: I incorrectly stated that Javascript has dynamic scoping. It actually uses a mix of lexical scoping and contextual binding. Dynamic scoping is significantly different than contextual binding. This post has been updated to reflect correct information.

Eight-ish years ago, I wrote a blog post about the importance of programmatic scope. At the time I could have told you roughly what scope was, but I don’t think I could have explained how scope in Javascript actually worked. I could explain that some variables were accessible in different parts of the application and I could point at things and give a vague, hand-wavy kind of explanation as to how it all related. Only understanding that much served me well enough for a while, but when push came to shove, not understanding scope at a deeper level started to make development in Javascript difficult and unreliable.

Perhaps the most important thing to understand is what scope is. Variables are available to different sections of code based on how they are defined. Simply put, there is a lookup table that is provided at each layer of the code and this table contains all of the variable references a line of code may access based on where it lives in the source file or at execution time. Below is a visual demonstration of how this works in your code.

In order to write programs which are stable and predictable, it is really important to have a firm grasp on variable scoping and what this means in the context of the code you write. As it turns out, there are actually two major types of scoping. The first kind of scoping is lexical scope. The second type of scope is dynamic scope actually contextual binding.

As it turns out Javascript actually uses a combination of each of these. This blended approach to scope is, in my opinion, one of the largest sources of confusion for debugging and editing code in Javascript today. This post will focus on lexical scope, so we can get a firm grasp on, in my opinion, the simpler of the two scoping methodologies. I will cover the following lexically bound scope scenarios:

Lexical Scope Overview

Lexical scope is, in the simplest terms, association of variables in the program based solely on the way they are introduced in the source code. In other words, lexical scope will always follow the same rules when executing based solely on how you wrote the source code. Execution context has no bearing, so though inspection of the code alone, you can reason about which variables are available where.

The first example in the post is an explanation of how lexical scope looks when writing functions. Each variable is made available precisely where you would expect it based on the structure of the code. With the next three scenarios you will see how each of the lexically bound scopes work and how to apply them.

Global Scope

When people say “don’t use global variables,” what they really mean is don’t bind variables to the global scope. Globally scoped variables are available in every context and, when modified, can introduce all kinds of bugs and problems into your code. However, with ES6, we can define constants which are safe for global use. Let’s take a look at a good globally scoped value:

Global scope is typically reserved for constants and namespaces. Other items that are globally scoped are built-in objects and functions that are part of the core Javascript language. Although the global scope is a valid scoping target, it is best to take great care when using it.

Function Scope

In Javascript, up to this point, function scope has been the primary scope used for defining, assigning and maintaining variables. Function scope is a relatively safe place to define variables that will be used locally for work to be done.

The interesting point about function-scoped variables is, they are defined within a function but any functions that are defined below that function level also have access to the variables as well. There are caveats, but that is a discussion for another day. Let’s take a look at function-level scoping.

I feel the last call to parrot.say was completely unsurprising. HandyVar is scoped within the IIFE and is not accessible from outside the function. The item that is slightly more interesting is sayHandyVar. We access handyVar from sayHandyVar by referencing it directly. This is the nature of function-scoped variables.

By using function scoping, we can guarantee that our variables will remain unmolested by outside functions. This kind of data hiding gives us certain guarantees that our programs will behave more reliably and predictably as we develop. Due to this added stability, we can write larger, more complext functions without worry that we are impacting something we might not see until a bug shows up in production.

Block Scope

Block scope is old hat for anyone who has worked in other languages like C++, Java or C#. If you have a conditional or loop structure and you define a variable within that block of code, the variable is only available within that block.

Block scoping was introduced with ES6, and is defined with the let keyword. Theoretically, you could run around and replace all of your var declarations with let declarations and your program would work the same as it ever did… Theoretically.

Since var declarations only support function scoping, you might encounter some strange issues if vars were used inside of blocks and then referenced elsewhere in the function. This is due to variable hoisting. Basically, if you declare a variable with var, the declaration will be auto-hoisted to the top of your function. Let will not be hoisted. Let’s take a look.

Wait, what?? So much craziness happening here. The variable myOuterVariable is not hoisted at all. It lives only below the for loop. Not only that, but i only lives within the for loop. This means you get a much more strict isolation of variables you define.

Coming from a Javascript background, this might not sound so great. We have all become so used to being loose with our variable declarations, that let might feel restrictive. As it turns out, var isn’t going away (though I wouldn’t miss it) and let is giving us a way to isolate our variables in a clean, predictable way. This kind of scope isolation allows us to use counting variables without fear of program retribution. Take a look at this:

We were actually able to redeclare i for each loop, safely, and then manipulate it without worrying about whether we were going to affect the output. This opens a whole new world of opportunities to isolate variables and keep our programs tight, maintainable and predictable. I love predictable programs.

Finally (or TL;DR)

This covers the foundation for how lexical scope is handled in Javascript. There are three main lexical scopes a programmer can work in, global, function and block.

Global scoping makes your value available to the entire program without regard to safety or data security. The global scope should be reserved for constants, namespaces and core language functions and objects.

Function scoping makes your variables available only to the local function and all child scopes. When using the var keyword, variable declarations will be hoisted to the top of the function, though the assignment will still occur at the declaration line at runtime.

Finally, block scoping, which is new in ES6, gives us a way to manage variable scopes with block level granularity so you can protect your data and guarantee consistent function execution.

As it was said in the beginning, both lexical scoping and dynamic contextual binding are used in Javascript. We’ve managed to make it through the lexical scoping, so next time we chat, we’ll take a look at dynamic contextual binding. Until then, think about how you are scoping your variables and bring a little sanity back into your job.

Blog Post Notes

What Makes a Program Stand Up

Over the last year I have interviewed a lot of Javascript developers and I discovered something: many people working in Javascript don’t really understand what programming really means. What I am saying by this is, people can write code and make stuff happen in the DOM, but they don’t really understand why. Scratching just below jQuery reveals that most of a program is still essentially magic for people who promote themselves as developers.

If we look at professionals who regularly practice in other fields, even the most junior practitioner has a foundation understanding of what drives the profession. Lawyers fresh from the Bar understand law. Medical doctors, even in their residency, already have the foundation knowledge they need to diagnose and treat ailments. The most junior of architects have the physics, materials and design knowledge to understand what makes a building stand up.

Javascript developers, even at the most junior level, should understand what makes a program stand up.

History — Turing Completeness and Lambda Calculus

Let’s hop in our wayback machine and go back about 80 years. There was a guy named Alan Turing. He is (finally) known by the general public as the man who helped crack the Enigma machine through the use of computing and mathematics. Before the second world war (~1936), he developed the idea of a computing device which could, in theory, emulate any other computing device. This device is called the Turing Machine. The Turing Machine is important because it, largely, defines what we know as the foundation of modern computing.

With the advent of the Turing Machine came the concept of Turing completeness. Essentially, any computing system that could emulate a Turing Machine could be called Turing complete. Turing completeness is a key ingredient in the development of modern programming. Though Alan Turing was working with tapes and those who followed used punch cards, programming as we understand it today began to take form in the early 20th century.

Around the same time as the development of the turing machine (1936-1937), another mathematician by the name of Alonzo Church developed a new method of describing computing function and behavior, called Lambda Calculus (λ-calculus). Incidentally Turing and Church developed these computing ideas separate from one another. Lambda calculus described a foundation for what we know as functions in programming and, more specifically, functional programming. λ-calculus is relatively inscrutable for the uninitiated, but a good example of what it looks like is the following:

λ.x.x => (λ.x x) = x;

This particular example draws upon Lisp notation to provide a little clarity. Below are the same functions in Clojure and Javascript:

In the great tradition of 1, 2, skip a few, 100, I’m going to bypass the invention of Lisp, C, C++, ML, OCaml, Haskell, Python, Java, Pascal, Basic, COBOL, etc. Though all of these languages are important in their own right, they are all informed by the same underlying principles.

If we come back to the modern day, Turing completeness and Lambda calculus underpin all of the things we know about good programming and reliable software. Turing completeness gives us the notion of branches and flow control in our favorite general purpose programming language, Javascript.

Conditionals and Branches

A computing system can be said to be Turing complete if it can emulate a Turing Machine. Although our modern computers are limited in memory and we, as people, are limited by time, a modern programming language can generally be considered Turing complete because it contains conditional operations and it is capable of accessing arbitrary amount of memory locations. In other words, because Javascript, much like other modern languages, has if statements and can store and retrieve arbitrary data in memory, we can consider it Turing complete.

Another way of looking at this is Javascript is a Turing complete computing system because you can write code like this:

Let’s be honest, this is a really trivial function, but there is a lot of history that goes into it. We declared a function which was stored in memory. Inside of that function we test a passed value with a conditional. When the conditional is satisfied, we perform one assignment operation. If the conditional is not satisfied, we perform a different assignment operation. After the assignment is complete, we return the result. For such a small, simple function, there is a lot happening. Consider what would happen if conditionals (programmatic branching) didn’t exist. How would we ever do this? All of our programs would look like this:

This program is really useful if, and only if, you ever only need to do just those four things in succession. If one action fails, the program would continue running and disaster could occur. For instance, suppose that was the program for a robot on an assembly line and a part came through oriented incorrectly. That part could translate into a completely ruined product. Whoops.

The idea of conditionals and the way they impact programming can be summed up by a joke about engineers. An engineer is going to the store for his wife. She told him “buy a loaf of bread and if they have eggs, buy 12.”

The engineer returned with a dozen loaves of bread.

The engineer’s wife said “why do you have so much bread?”

The engineer replied “they had eggs!”

Branching, as far as I am concerned, is the most important concept to pave the way for any modern computing. All other elements of modern computing would not exist without it. Branching, however, is necessary, but not sufficient to define modern programming.

Reusability — Reusable Logic, Objects and Functions

The other core element of modern computing without regard to the implementation details, is logic reuse. We like to say code reuse, but what we really mean to say is, “I want to define some logical behavior and then just refer to it elsewhere.”

Logic reuse comes in several forms, but the ones best recognized are functions and objects. We can claim that there is third type of reuse which comes in the form of modules or namespaces, but can’t we squint a little bit and say those are just special cases of objects?

In Javascript we get the benefits of our forebears because we get all of the object/class goodness that comes with heavily object oriented languages like Java and C++, but we also get all of the functional wonderment that comes from languages like Lisp and Haskell.

Object logic reuse could look a little like this:

The functional paradigm in Javascript looks like this:

You’ll note we are already doing some relatively advanced operations, and the code is rather brief. This brevity is due to the nature of logic-block, or more correctly algorithm, reuse and abstraction from the deepest building blocks in a computer software system. As we get further from the computer hardware, we get more power with fewer keystrokes. The language becomes more like English and less like bits.

Recursion + Conditionals => Looping

The next piece of the modern language puzzle is recursion. Recursion blended with branches is, in my estimation, the easiest way to break down looping structures into the base elements to add visibility. Recursion on its own is not simple, but it is key to understanding why loops work they way they do. Here’s a really basic recursive algorithm for adding values:

You’ll note we did not use a standard looping structure for this. This is a special type of recursive function called a tail recursive function. What this means is the call back to the original function happens as the very last statement in the function. This behavior is very similar to the way a while loop works. Each iteration checks the return condition and the loop exits if the condition is met. If the condition is not met, the loop continues.

The problem we encounter with algorithms like this is you can easily fill all available memory with a large enough array of values, which can cause all kinds of problems. This is because Javascript does not support tail-recursion optimization. In other words, you could write this recursion any way you please and it will perform essentially identically. Due to the growth nature of recursion, looping constructs become significant. We could rewrite this loop with a standard while in the following way and not crash a browser, server or any other device you might be running your code on.

You’ll note that, while this will perform the operation more efficiently than our recursion, we have now tightly coupled our addition logic to our exit logic. This tight coupling is what, ultimately, interferes with the innate understanding of the loop and precisely when it will exit and allow the function to return our sum. It is equally important to note that this is the preferred way to handle explicit looping in Javascript.

We do have an alternate methodology which abstracts away the condition altogether which reintroduces the concepts we get from Church’s λ-calculus. If we select an appropriate higher-order function, we can extricate our addition logic and abstract away the express syntax for looping, leaving the real intent, alone.

Although this is not what any mathematician would ever call a formal proof, we can see immediately that the functional aspects of Javascript introduce branches in such a way that we can guarantee Turing completeness in much the same way as the imperative logic could.

Conclusion

Much like any other profession, programming has a storied history and the groundwork for what we use today takes advantage of some very important foundational concepts. Even though we have been abstracted away from the hardware and we are no longer using punch cards, all of the groundwork laid by Turing and Church as well as many others who followed define physics, materials and design knowledge we employ today when we apply experience to new problems across many industries.

What makes a program stand up is not just understanding each of these concepts in a vacuum, but how they work together to create new solutions to existing problems. We have to understand and evaluate the interrelation of the core components of what makes a program work, and apply them in a way that makes software not only functional, but maintainable and clear in intent.

Simply knowing there are conditionals, loops and code reuse is possible does not, by itself, make the professional programmer skilled. It is understanding the interrelation of the elements in a program that allows a professional programmer to skillfully design and execute software that will solve problems and provide those professionals who follow to understand the choices that were made and enhance solutions as real world problems continue to change and grow.

Blog Post Notes

Related links:

Mainstay Monday: Inheritance

This is the first in a new series I am trying out on my blog. Every Monday I want to provide a post about some foundational element of programming and how it relates to Javascript development. What better place to start than inheritance?

Object inheritance is one of the one of the least understood foundation Javascript topics I can think of. Even if a developer is comfortable with prototypal behavior and instantiating prototypal objects, handling inheritance is a layer which is more obscured in the Javascript than classically designed, OO languages.

Let’s discuss the object prototype. To start with a simplified definition, an object prototype is a set of properties associated with an object that defines the foundation functionality an instance of the object will have. In other words, anything you put on an object prototype will define what that object will be when you perform a ‘new’ operation.

Let’s take a look:

This is about as simple as it gets. We define a function attached to the prototype, let’s call it a method to keep parity with classical OO languages, and when we get a new instance, the method is attached to the object we get back. Once you are familiar and comfortable with this syntax, it’s easy to do and easy to understand. The pitfall we have here is it’s a little convoluted. ECMAScript 6 (ES6) introduces a new, more classical notation, though the underlying behavior is still the same as it ever was.

The code is a little shorter and, hopefully a little more declarative of intent, but the end result is identical. Now, in classical languages, there is a concept of object hierarchy. OO languages provide a clear construct for how this is handled with a special keyword. Let’s call this inheritance keyword ‘extends.’ Let’s pretend our classical language uses this ‘extends’ keyword and create a child object with it.

You’ll note that we just got the parent properties for free. Extra bonus, SURPRISE, that’s ES6 syntax. It’s nice and easy. Most of us are still working in ES5 and in ES5, the times are hard. Let’s have a look at what inheritance looks like when you don’t have all the handy dandy syntactic sugar.

This is a lot more verbose than our friendly ES6 syntax, but it’s pretty clear the result is the same. We end up with an object that performs a new operation and directly inherits properties from Fooer. This verbosity along with the hoops you have to jump through makes it pretty obvious why people don’t introduce object inheritance in a beginning discussion of Javascript.

Regardless of the obscurity, we can try this and see inheritance really works and it adheres to the kinds of expectations we would bring from languages like Java, C#, PHP, etc.

By adding object inheritance to our arsenal, we can look back to our computer science forefathers and apply the knowledge they shared in books like the Gang of Four Design Patterns book. Concepts like inheritable DTOs become usable in Node and in the browser and we can begin to normalize our coding practices and use sane conventions in our profession to help us focus on the task at hand: solving new problems.

On top of all of this, we can see deeper into what is really happening with prototypes. When we understand how prototypes handle object properties and provide a link to the parent object, we can better understand how to leverage the finer nuances of the language for a more powerful programming experience.

Blog Notes

For an abstraction layer to handle inheritance, please see my gist.

Don’t Talk About My ObjectMother That Way

When last we met, we talked about setting up unit testing for Javascript. I’m sure anyone reading this blog is at least aware of the idea of software design patterns. There are all of these known challenges with canned solutions. If the solution isn’t ready out of the box, it is with just a little bit of tweaking. Something you might not be aware of is there are unit testing design patterns too.

Er… What?

I know, most people think of unit testing as either something they tolerate because it’s required or, at best, a list of tiny little functions that guarantee that a particular behavior matches the expected business requirement. Where is there room for design patterns?

Many patterns come in the form of best practices, but there is one that is at the top of my list of all time favorites. The ObjectMother pattern is a design pattern tailor made for unit testing. Technically you could use ObjectMother in your everyday programming as a factory or something like that, but today it’s all about testing.

Let’s start by looking at a unit test for two different functions that require data from the same contract. I’m just going to hand-wave past what the functions do, because it doesn’t really matter right now. Right? Right.

That is a LOT of typing for two little tests. It’s especially bad since the two different objects are so similar. Now, we could combine the two object setup blocks into a single beforeEach at the top, but what if this same data object is necessary in another test in another file? What if, worse than that, there are several modules that might interact with this data, each capturing data for a particular purpose which could be unrelated to the data module we tested here?

The almighty DRY principle would tell us this is inherently flawed. There is a code smell and that smell is one of the big reasons I hear people hate writing unit tests. What if we could actually DRY out our unit tests in a sane, maintainable way?

Enter the ObjectMother pattern.

Here’s what the mother of this object might look like:

With this defined, our test code becomes much simpler to write, read and maintain. If we use our new object mother, here’s what our tests become:

It’s like magic, right? We just eliminated 10 lines of code we were using in our original test file and now we are able to focus on the problem, testing our functions. What’s even better, we have now centralized our data example so any other tests can use it too and we only have to modify it in one place to expand our tests. If the contract were, heaven forbid, to change, we can change our data in our mother file to match the new contract and then identify any breakages, update functionality and guarantee function and data parity. This is a HUGE win.

For small sets of tests, and relatively simple data structures, this is perfectly acceptable. What happens when you have nested data structures and complex logic to interact with it? Now you have data interdependencies and our simple functions aren’t going to be sufficient.

This calls for other, well known, patterns. We can draw upon the Factory and Dependency Injection patterns to make this better. We can employ initializing functions and initial condition objects to define a more robust interface.

Since these requirements arose as I was working through unit testing scenarios in my day to day life, I created a library, DataMother.js. DataMother allows you to isolate layers of objects and register them with an injection system. At test time, you can use DataMother to handle your data requirements much like we did above which actually made unit testing with data so easy, I actually started looking forward to it.

Weird, right?

Anyway, whether you use the naive method outlined earlier or a more robust solution like DataMother.js, use the ObjectMother pattern in your testing and bring the joy to unit testing data-driven functions that you have in the rest of your programming life. Unit tests and data can be friends!

Blog Post Notes:

The ObjectMother pattern was first discussed (as far as I know) in 2006 by Martin Fowler.

The links below are assembled from the links in the post:

(Not) Another JS Testing How-To

There are lots of posts about how to write your first unit test in Jasmine or Mocha, and many of them draw directly from the Jasmine how to. Let’s pretend, for a moment, that you are a developer who is already familiar with unit testing and what you really, REALLY need is a way to actually get things started without having to read a whole host of how-tos, setup documentation etc, when all you really want to do is get to unit testing.

First, let’s get the Grunt versus Gulp conversation out of the way. I say neither! Though task runners can make CI much easier, this post is about getting a quick start into actually doing unit testing. By setting up a good, solid base configuration, moving to a task runner can be as simple as just applying the configuration you have with the runner you choose. Perhaps you like Tup…

Anyway, now that we have all that out of the way, let’s talk tooling:

When we are done, this is the toolset you will have for your testing needs:

  • Node and NPM
  • Jasmine
  • PhantomJS
  • Karma

The biggest hurdle you have to cover to get everything up and running is to get Node.js up and running. For most reading this article, all you have to do is visit the Node.js website and click install. You will get the right binary and you will be off and running.

Once Node.js is installed, it is all downhill. I created a Github project that you can use to quickly get started with unit testing on just about any platform. You can either download the release, or follow the directions below:

Once you’ve copied this repo one way or another, setup is really simple. You will need to install Karma and Phantomjs globally, so I created a handy one-time use script you can run. After the global installs are finished, you can run the project specific installer and you’ll be ready to rock and roll. Open a console wherever you cloned the repository and run the following commands:

No fuss, no muss. You’re welcome. ; )

You’ll see lots of packages stream by in the console. Once everything installs, you’re ready to start testing. It’s not exactly exciting bedtime reading, but I definitely recommend looking at the Jasmine website. Their documentation is written as a set of unit tests for the framework, which is novel, but it makes things a little hard to figure out on first read.

Let’s have a look at a (barely) annotated first unit test:

When you start writing unit tests for your code, be sure to review the Karma configuration file in the spec folder. Most settings can be left exactly as they are, but the paths should be updated to match your project structure. I’ve included the code below so you can see the lines which need to be updated:

Although this isn’t the snappiest blog post I have written, I have gone through this process so many times I have created templates for different kinds of projects just to save time and simplify the process of setting up unit tests, linting, ES6 transpilation, code coverage, etc.

With so many different configuration options, limited documentation and roadblocks I have encountered as I have gotten systems set up, I wanted to put something together that might help save someone else a little pain and suffering. If you have feared unit testing in Javascript because of setup troubles, consider this your personalized invitation. Unit test your code and make the web a better place!

Similar posts in Coding, Javascript, Unit Testing

Browser-side Isomorphic Javascript

With the advent of Node, there has been discussion of isomorphic Javascript.  The general idea behind this is code written for server-side purposes can also be used for UI purposes. The problem with this notion is, it doesn’t account for browser UI/middleware considerations in the browser.

As client-side development progresses and software as a service (SaaS) and single-page applications (SPAs) become more common, UI developers continue to program based on user interactions with the view layer and the underlying logic gets woven into the UI code, littering data logic with DOM related code, which tightly couples the UI code to the data code, creating complicated, unmanageable software.

What ends up happening is code gets duplicated to serve the same purpose, and then the code gets out of sync. Bugs creep in and pretty soon the software starts getting cracks in the facade. Even frameworks that are intended to avoid this kind of behavior, like Angular, are built in a way that allows for divergent code.  Let’s have a look at a snipped of code that could diverge quite quickly, in Angular.

Obviously there was some cutting and pasting that went on here.

What happens when the requirements are changed? Will this developer remember that the regex needs to be changed in two locations? Will this developer even still be working for the same company?

Even if this is remembered once, it is almost guaranteed to be forgotten about. This is especially heinous because there are clearly two different concerns being served here. One place the UI is handling input validation so the user can get immediate feedback, the other is likely to be related to handling validation before data is sent to a service somewhere.

It is not obvious even from this simple example that DRY could be applied here. Of course it can, but the solution is not completely obvious. Since this is not a post about Angular validation, I will leave the Angular-specific details as an exercise for the reader. Instead, let’s take a look at a more general solution.

Obviously the script handling the validation is pretty general so we’re probably safe to start there. Let’s keep it. That means all we really need is validation for the UI. Let’s have a look at something that would give us the behavior we want:

Now our element has the same validation attached that our outgoing data will use to ensure everything is on the up and up. Honestly, though, this is a fine first pass, but you and I both know this isn’t the only validator you are going to use to handle your user inputs. Why don’t we do a little more cleanup and write something we can really get some mileage out of.

Now, that’s what I call DRY code. Now we have taken one piece of logic, isolated it and applied it in the places we need it. Sure it took a little extra code to get us there, but you can see the difference it makes. Now if someone comes along later and says “gosh, it would be great if the ID values could start with efg instead of abc,” anyone who is currently working with the code can go and update the validation logic and it will update the requirements everywhere.

What’s even better is, now we have a UI validator that we can apply any kind of validation logic and not need to continue writing and rewriting UI logic to handle all of that mess. Extra special bonus is this entire thing is written in vanilla Javascript, so it’s extra small, tight and as fast as we could make it.

When you do this in your code, go ahead and pat yourself on the back. You deserve it.

In the end, what people are really talking about when they say isomorphism, what they really mean is “don’t repeat yourself.” When that’s the goal, then isomorphism doesn’t have to be limited to client/server applications. Take the lesson and run with it. Make your code better and your users (and your boss) happier. Let’s use isomorphic code to make the world a better place.

Comments Off on Browser-side Isomorphic Javascript

Everyday Functional Programming in Javascript

I gave a talk at the beginning of the year about functional programming. Someone asked “can you do functional programming little by little or do you have to do it all, all the time?”

When I answered, I felt I didn’t give them the answer they deserved or that I could have given.  This is my answer. Yes, you can do a little or a lot. You can write functional code little by little and solve things without changing your life and your career.  You can write programs that aren’t academic or theoretical. You can write everyday functional code.

So what does everyday functional programming look like?  Unless you work somewhere that you write in Lisp, Clojure, ML, F#, Haskell, etc, then it doesn’t look anything like the high-brow academic tutorials you see most often.  You don’t talk in monads and exclusively pure functions.  It’s not an ivory tower. At best you are a warrior acolyte of the functional cloth.

State is a thing.

So, when you are working in functional languages, state is a difficult knot to untie. Since values are immutable and shared state is the work of something unholy and evil, handling things like state machines becomes a chore. Who wants to go to work and think “today is the day I have to tackle the beast. I hate today?”

Not. Me. Thanks.

Sometimes you really need state. You actually need to know what happened and what is coming.  Sometimes you want something that you can mutate and something that is transitory, but still in memory. Hi to all of you Haskellians, yes I know there are other ways of doing that kind of monkey business, but I just don’t wanna. It looks a little too much like work and a little too little like fun.

First class functions are for everyone.

Now that I got the state stuff out of the way that OO does just so well, let’s talk about what functional workflow looks like in my happy little world. Arguably the thing I feel differentiates functional programming from programming that isn’t is the beautiful higher order function.

I mean, it’s magic right? Higher order functions, I mean look at this:

That’s what I am talking about. Functions that take functions as arguments. It’s all kinds of awesome, right?

Okay, in all seriousness, the real awesome comes when you start blending pure functions in with your stateful code and moving all of that stateless logic into something that makes more sense for what you are trying to accomplish. Let’s have a look at one of my all time favorite constructs. It’s what makes my world go ’round: either.

Watch this.

All of this because, honestly, who needs all the conditionals? Do you care about the conditional logic or do you just care about the data? Personally, I think conditional logic is the devil. I mean, honestly, the worst bugs and the most  difficult mess comes from all of these horrible, horrible conditionals. Let’s cut to the chase and just make it right.

Here’s something even more amazing, ready for this? ARE YOU READY? Yeah, you’re ready.

I mean, DUDE, you can skip all of the worrying. If something null happens, you just pretend it never existed and everything turns out just fine. With just one new function, all of a sudden you get  all of the functional goodness that Javascript has to offer.

What does either look like?

That’s it. It’s the gift that keeps on giving.

At the end of the day, what I am really getting at is this: everyday functional programming is all about cutting to the core of what you want to do and eliminating the conditions, unnecessary shared state and error prone code so you can keep your sanity. It’s not about all pure functions all the time. It’s not always about monads and currying. It’s about the little things that make a big difference so you can do your best work.

Callbacks, callbacks, callbacks!

Waiter,

There’s a promise in my spaghetti.

***

So, dig, I like promises.  People I work with and people I talk to think I don’t but I really, genuinely do. Promises (in a computer science way) are just plain awesome.  Here’s the idea:

Program module: Yo, system, I want to do something and I want it to happen on another thread so I can keep doing stuff.

System: Okay. I’m doing it. Here’s an IOU, let me know when you are ready to collect.

Program module: Okay, I need that stuff now.

System: I’m not ready yet. Please hold.

Program module: okay, I’ll wait.

System: Okay, I’m done now, here’s the stuff you wanted.

Program module: Cool, thanks. Game on!

What happened here?  Basically a promise was issued and the program continued running with an async process continued in the background. When the program was ready for the data, but the data wasn’t ready, the promise became a blocking operation. Once the system was done, it delivered what was needed and the block was released.  This is awesome because you don’t end up with something that blocks up front. This can be annoying when you need something to appear completely transparent and non-blocking.  Such is the way of the world.

Javascript promises are, let’s just say… different. Everyone likes to say “oh they stop callback hell! They are the magic bullet!” Incorrect!

Promises are just syntactic sugar over a callback structure, which basically seems like a big fat lie to me. I don’t like the idea that I am “getting rid of callbacks” and really all I am doing is tucking away functions in a place where I have to do a TON of work to get tests around them. I have seen some of the worst code ever written inside of promise callbacks because “hey, it’s promise. It’s cool, man. You don’t need to test that.”

*cough* yes you do *cough*

Did you notice how I said “promise callback?” Yep, there it is. Promises and callbacks are still the same. You still pass in callbacks. You still have to handle the asynchronous nature of it all. This is where I climb to the mountaintop and proclaim “the cake is a lie!”

Then there is the q.all argument:

“What if you need to do a bunch of things and then call back? That’s like… complicated, man.”

It is. This was one the one concession I make… well, I USED to make. Q.all is pretty cool. Don’t get me wrong, anything that will bundle up a bunch of async calls and then hang out until they are all done, THEN callback is pretty darn nifty.  The problem is you are still introducing this idea of promises into the mix.  Stuff happens, the spell is woven and magic happens… Magic that is basically untestable.

So, let’s stop trying to paint the callback turd with a single layer of abstraction that makes things murkier and more difficult to understand. Promises are magic that have become lingua franca of async spaghetti. Instead, let’s have a look at a handy new library borne of Node and easily pulled into the client: Async

Dear promises, never send to know for whom the bells tolls; it tolls for thee.

Async deals with callbacks differently. Instead of wrapping everything up in a nasty set of promise.then().then().thens, try async.waterfall(). It’s like magic:

async.waterfall([
firstOperation,
secondOperation,
thirdOperation
], finishFunction);

Now your code actually says what it is doing. Callback hell is gone. Promises are eliminated. All is right in the world.

But what if I want to do a bunch of stuff that doesn’t happen in serial? Parallel. Check it, yo:

async.parallel([
anOperation,
anotherOperation,
yetAnotherOperation
], finishFunction);

It’s like magic right?

In closing, all I would ask is, if you are going to write a bunch of async stuff, please give me and everyone else on your team a break. Async is the way to righteousness and the light. Promises are great when you absolutely, positively must have it sometime later, but most work can be done with async. Give it a try and make your code a better place.

Similar posts in Coding, Javascript, Site Architecture

To New Beginnings

Wow! It’s shocking that the last post I wrote here was almost a year and a half ago. I guess it’s been busy!

In that time I worked for an education company, got laid off, found work at a startup and wrote a LOT of code. Am I older? Definitely. Am I wiser? I certainly hope so. If anything I gained a lot of insight and found evidence for my suspicions.  User experience is crucial and the only people who can guarantee a good experience are the people who create the software that users touch.

I spent much of the past 10 years trying to figure out what I wanted to be when I grew up.  I went through phases of user experience, accessibility, project management and research.  All the while I was busy writing software.  What I ultimately discovered is I like writing software.  I like creating things.  There’s a rush that I don’t get anywhere else but there.  That doesn’t get me the answer I was necessarily looking for, but I suppose it gave me something I could hold on to.

Another important thing I discovered along the way is there are a lot of people who have a lot to learn (including me) but I discovered something I didn’t believe before now: I have something to share.  For as much as I don’t know I have been fortunate to learn a lot of lessons and I can share that with people so, maybe… hopefully, they can either grow from what I experienced or, at least, I can help buoy their spirits a little by showing that everyone makes mistakes.

Wisdom is what you get when you don’t get what you want.

I didn’t come up with that phrase, but it sure sums up what I feel to be true.  Just because things didn’t work out the way you originally planned or wanted doesn’t mean that things didn’t turn out at all. Failure is such a better teacher than success that I just can’t imagine why people fear failure so much.  I aim to fail every day. Failing is awesome. Success just means you’re done, but when you fail, that means you went from working on something routine to a fascinating new puzzle. What a great opportunity!

I could go on and on like this for pages, talking in circles and rambling about vague pasts and lessons learned, but that isn’t what I set out to do.  This post marks the beginning of a new era for me and this blog.  I won’t promise that I will never post long diatribes about strange new discoveries I may or may not have uncovered myself.  What I can say is I have a focus today like I never could have imagined when I started writing this blog years ago.

I want to make stuff awesome and make awesome stuff. I want you to do the same.  I still want to make the web a better place, but maybe, somewhere along the way, I, or we, can actually make software better.  Let’s toast to new beginnings and new projects.  Here’s to all the projects that never quite were and the ones that are yet to come. Let’s make software. Let’s make it great. Let’s make it together.