Mainstay Monday: SOLID – Single Responsibility Principle

Starting this post and for the following four Mainstay Monday posts, I am going to go through the SOLID principles as put forth by Bob “Uncle Bob” Martin and Michael Feathers. SOLID is a foundational set of principles to allow programmers to evaluate their code by and refactor to in order to reduce bugs and increase stability. Originally SOLID was presented as a tool for object oriented design (OOD), but I contend that many of the principles apply to the functional paradigm as well.

The first principle of SOLID is the Single Responsibility Principle. As the name states, single responsibility is a heuristic we can use to evaluate whether code we wrote is trying to accomplish too many different tasks. When code does too many things at once it allows bugs to creep in undetected. Following is a function that, at first glance, looks pretty small and innocuous, but actually tries to accomplish several different tasks at once.

Just as a brief review of what is happening here, we have a state variable captured in a closure, called latestSum. The returned function does a little validation, a little arithmetic and a little state modification. For 4 lines of executable code, that’s actually quite a bit going on.

Let’s do some refactoring and tease apart each of the different actions we’re performing and create separate functions for each. This may not immediately seem like the best way to go about things, but it will make our issues a little more transparent. Here’s a new, refactored function that does the same job.

Composed adder is a little cleaner now. Each of the things it used to handle directly have been abstracted away and then reintroduced as function calls. Now our function is a little less explicit about the discrete steps needed to accomplish the work, and our adder function can be considered more of an execution layer which merely combines the steps needed to fully process our request.

As it turns out, however, a big mess of functions like this can turn ugly in a heartbeat. Beyond the obvious trend toward one or more pyramids of doom, we are handling a memory state in a rather sub-optimal way. When state and functions that modify that state live closely together it can sometimes be helpful to collect the entire block of data and functions into an object which manages its own state.

When we create a class around this concept of an adder with a persistent memory, we can make nearly a one-to-one conversion from a functional form to an instantiable object. Let’s refactor and take a look at the resulting object.

Aha! Once we have made the transition to an object oriented paradigm, it becomes clear that we are still, in fact, not adhering to the single responsibility principle. Our object, memAdder, is still doing all of the same things our original function was doing. This is why our function looked so messy, we kept all the clutter!

As people who know me understand, I am a proponent of “everyday functional programming.” This means that doing things in a purely functional way in theory sounds wonderful, but sometimes objects happen. The beautiful thing that can happen, however, is sometimes we start looking at a big, ugly object and then functions happen.

Let’s use a modified strategy/factory pattern returning functions instead of objects to abstract away all of our validation and computation logic and leave the object managing the thing objects manage best: state. When we do this, we can fall back to our preferred pure functional approach for the grunt work, which will be selected and managed at runtime based on user need, meanwhile we have an object that can compose functions on the fly and maintain a running memory of the latest computation peformed.

As we can see, the new object memComputor has been reduced to a single responsibility. Hooray! That’s what we set out to do. memComputor is instantiated with a computation method and a validator, so it contains no computation or validation logic of its own. ComputeAndStore does exactly that. It takes the desired functionality, composes it on the fly, fails the attempt if it is invalid, otherwise the computation is performed and the output is stored and returned.

Meanwhile on the factory front, we have all of our actions lined up. We declare the methodology we need, receive functions and we have a pair of pure functions that are reliable, bug-free, or as close as we can make them, and ready for injection into our state-management object.

It seems like a lot of code to, ultimately, do a simple addition problem. If the goal were addition, I would agree. Ultimately, however, what we really built here was the foundation for a system to manage expensive actions that we might want to perform once and then reference again and again, like the union or intersection of a large list of data, perhaps.

To sum up everything we’ve gone over, the Single Responsibility Principle is a heuristic tool for evaluating whether a block of code, object-oriented or functional, is performing the correct actions to accomplish a single goal or if the code is taking on too much and should be refactored to solve the problem in a more granular way.

With many programming problems, identifying the right granularity can be difficult, but by using some of the well known and battle tested tools and solutions like the single responsibility principle. By adding SOLID principles to your arsenal of tools, your programming will get better and your ability to solve even greater and more complex problems will become a question of breaking them down into the right pieces.

Contracts for Better Code

With programming languages which have a greater draw for classically trained computer science types, there is a common discussion of contracts and data expectations. Contracts are so inherent in the code that it’s hard to see a declaration without one. Type systems emerge from the idea of contracts and every function, constructor and return path comes with an expectation that is defined and declared in the code.

Javascript, being dynamically typed and a little loose with the morals, attempts to sidestep contracts altogether. Function arguments are little more than a strong suggestion to the programmer, and every function returns something even if that something is merely the undefined type. Contracts are just not something we do.

Here’s an example of exactly how squirrely Javascript can really be.

Obviously each of these functions does essentially the same thing, but in the last example a and b are nothing more than a suggestion of how you could use the function. You could run addSuggestion() and get 0 or you could run addSuggestion(1, 2) and get 3. There’s no requirement that you actually adhere to the contract at all.

You are doing it wrong.

There, I said it. Mucking about with all of these bits and pieces that may or may not exist and allowing programmers to play fast and loose with your carefully constructed function is just plain wrong. I makes me want to take a shower. It’s like the midnight movie on the horror channel: gross.

Rule number one of contract club: You ALWAYS talk about contract club.

If someone created a contract in their function they are setting expectations. If you don’t play by the rules someone set in the function, you should not expect the function to work properly. It’s just that simple. The contract is there to save you from yourself.

At this point, I think I should mention, I understand that Javascript doesn’t support function overloading, so you can’t create optional variations on a function and the loose requirements around the contract are there so you can get something akin to overloaded functions.

To this I say hogwash!

Actually that’s not true. Optional arguments are good, however it is better if we use them in a safe way. Overloaded functions, even in languages that allow them, can get dangerous. It’s preferable to write code that says what it means and does what it says. Let’s take a look.

That may not be the most beautiful code I’ve written, but it illustrates the importance of what I am saying. Here we can see that there is a function, buildUrl, which takes four parameters. Hostname is required, but all of the rest are optional. Once we get to the specific implementations of what we are actually doing, the contract becomes a firm handshake and it’s backed by the interpreter threatening to throw an error if something goes wrong. Mind you, the interpreter is going to just concatenate a whole bunch of undefined values, but that’s beside the point. You won’t get what you want if you don’t meet the contract.

So, there is another side to the contract that is also illustrated here. Regardless of what happens, you can guarantee you will always, ALWAYS get a string back when you run buildUrl. This is the promise made by the person who wrote the code before you came along. So, on the one hand, you must meet the requirements of the contract in order for the function to properly execute. On the other hand, you are allowed righteous indignation when you expect a string and you get a boolean or something else.

Return types are contracts.

When you, as the developer, write a function and claim you are returning a specific type, understand that the next person will hunt you down with hungry dogs if you promise a string, but sometimes return an object. What is returned is really, REALLY important. People rely on it. Imagine if this happened:

I mean, that was downright malicious. Who goes around saying they are returning an array and then they return null. That’s seriously sadistic. What’s worse is, if listify was buried somewhere in a library and all you had was the crummy documentation they wrote, you would never be able to figure out what you are doing wrong to cause listify to return null.

I dunno, it just blows up sometimes.

The short version of this post goes a little like this: When you write a function, you are writing a contract. That is a contract you are required to honor and you can, almost always, expect the programmer who uses your function to adhere to that contract.

The longer sum-up goes more like this: A contract is a guarantee. The guarantee that is given states expectations for what the user will do and it provides assurances about what the user will get in return. Contracts revolve around data, and everything is data. This means that regardless of what you are writing or what you expect, in Javascript, you should always say what you mean and do what you say.

By providing a strong contract for the user to rely on, you are making the world a little better place to live in. You are giving guarantees when so many programmers around you might not. Best of all, when you write a good data contract in your functions you can come back after a year of looking at something completely unrelated and get back up to speed almost instantly on what goes in and what comes out. Doesn’t that sound like better code? It does to me.

Mainstay Monday: Solving Problems With Recursion

If you have been writing Javascript for any amount of time, you’re sure to be familiar with standard loop structures. For and while blocks are part and parcel of the modern programming experience. On the other hand, if you haven’t done a data structures and algorithms course, you may not be familiar with the term recursion. Recursion is another methodology for handling repeated behavior, but it is useful for a completely different set of problems.

Before we start looking at the kinds of problems recursion is useful for handling, let’s discuss what it is. Recursion is the process of calling a function from within that same function to perform the operation again. Typically this is done with some reduction, modification or subset of the original data. A great, and simple example of a recursive algorithm is the Greatest Common Devisor (GCD) algorithm.

In order to understand what we are looking at with recursion, let’s first take a look at an iterative solution to our GCD problem. Euclid would tell us this is the most inelegant solution he’d ever seen to solve this problem, but he’s not here, so we can do what we want.

This function will find the GCD every time, but there is a lot of variable manipulation. With the variables being swapped around so much, it becomes difficult to follow what this function is really doing. Nonetheless, there are benefits to writing out GCD function this way that we will discuss in a moment. Now, let’s take a look at the recursive GCD function.

This second function actually accomplishes the same task as the original, but in a single line of executable code! Clearly recursion can provide a simpler, terser way of framing certain kinds of problems. In this case, we solve one step of the problem and then let the recursion do it over and over until we get an answer. This shorter syntax comes with a cost: memory.

Our while loop, though a little harder to read, takes up, effectively, a constant amount of memory and processing cycles. When you enter the function, variables are declared, memory is allocated and then the loop works within the constraints of the variables we define. Our recursive function operates differently.

Let’s add an array into our first function and watch what happens when we push values into it while we are computing everything. This will give us some insight into what is happening in memory as our recursion is working.

This is just a rough approximation, but you can see how more and more memory gets allocated to handle the recursion. We can generally consider this kind of behavior in our programs bad. As the algorithm finishes up, we can see the memory allocation is 8 integers.

The size of an integer lives somewhere between 2 and 8 bytes, so let’s call it 4 bytes and meet in the middle. This means that just the storage for the numbers we were computing took up 32 bytes. That may not seem like a lot, but considering our original algorithm took about 12 bytes, this is a pretty substantial overhead.

Fear not! All is not lost.

Okay, so recursion may not be the most efficient kid on the block, but sometimes it actually, really makes sense. Suppose we had a tree that you really, REALLY need to search and find something. You could write an iterative solution to search the tree, but that involves trickery we don’t have time for in this post. Instead, let’s suppose the tree is several layers deep and each layer contains several intermediate nodes. Here’s what our algorithm might look like:

As you can see, we search the tree one edge at a time. We travel from node to node, moving up and down the levels until we find the element we want. If a matching element doesn’t exist in the tree, then we return null and accept our fate.

Wrapping this all up, there are always many ways to skin the proverbial cat and with each solution, there is a cost and a benefit. Recursion is an excellent way to solve some particularly tricky problems, but it comes with a cost, specifically memory and efficiency. Even with the drawbacks, sometimes it just makes more sense to use recursion and reduce the problem down to something more manageable.

We can consider looping to be a lightweight, electric chainsaw. It will cut just about anything you put in front of it, but it can make a mess. By that same notion, recursion is a scalpel. It’s not the right tool for every job, but when it’s handled with care, it can perform delicate surgery and remove warts from some of the trickiest problems in your code.

Dependency Injection Without A Framework (Or Pain)

If you’ve come from one of those big name, big OO frameworks, you are probably used to the idea of an Inversion of Control (IoC) container and dependency injection. If you have worked with Angular, you’re probably familiar with their dependency injection system. That’s all great, but what if you aren’t one of those people?

As it turns out, dependency injection (DI) just isn’t that hard to wrap your head around. When you talk to someone who has worked with one of the big DI systems like AutoFac or Spring, it can sound like DI is an enormous deal and could take years of practice and experience to get comfortable with. Here’s a little secret: there’s no magic. It’s not hard.

First, let’s talk about what DI is; it’s injecting stuff into your environment that you depend on. Dependency. Injection. That’s it.

You’re welcome.

Seriously, though, let’s have a little look at what DI looks like in a very hand-wavy kind of way with a class in ES6.

Obviously we know nothing about compontentFactory or widgetizer, but that’s alright. All we really care about is that we know widgetizer has a method that processes a context and componentFactory has a create method that takes a processed context. The black boxes that are these objects really doesn’t matter at this point in the application. All that matters is the API.

Most of the time when people see this kind of implementation, they construct each of the dependencies one of two ways. Either they instantiate the objects inside of their class or they instantiate their objects as they construct their class. To this I say ‘gross.’ The practice is so bad I can’t bring myself to give an example.

Instead, here’s how we are going to do this. We’re going to use the factory pattern and create objects as we need them. Once we have a factory, we can build new widgets without breaking a sweat. Here’s what that would look like.

The code is so simple it practically writes itself. What’s even better, if you are writing unit tests (you should be testing all the f**king time) then the setup for your tests becomes so easy even a junior WordPress developer could figure it out. Here’s a little Jasmine for flavor:

Your unit test setup is seriously only 8 lines of executable code. Let me repeat that… EIGHT LINES. Since the instantiation of your dependencies is completely disconnected from the instantiation of your object, you can easily swap them out for testing, or replacement with a new, better version, or… whatever. There is no need to hunt down every place you instantiated your dependencies because, if they have dependencies of their own, you can just build factories for them, too.

Now, I will say that all of the factories of factories of factories is going to get a little heavy and become a burden on your immortal soul, but that’s okay. I have another trick up my sleeve for you. Let’s create a registry and automatically handle factories out of a central object. Automatic factory… AutoFac… hmm.

Public Service Announcement: Before we start into the next part, I want to make this clear — If you aren’t using a framework, you’re building one.

Anyway, let’s build our registry.

Creating a whole registry system really wasn’t so bad. A little bit of recursion and line of slightly tricky Javascript later, you have a registry and object factory all set. Let’s take a look at what our registration and instantiation code would look like now.

A little recap, dependency injection is nothing more than providing your object with instances of the dependencies it needs. If your system is simple and your dependency tree is flat, you can easily get away with a factory to manage your dependency needs. If your system is more complex, you may need to create a registry to handle your components and the dependency tree. For better or worse, your dependencies are going to be complicated at that point anyway so avoid the pain.

The moral of this story is simple: never manage your dependencies along side the code that depends on them. Use factories to make your life better. If you take care of your dependencies, they will take care of you, so manage them wisely and profit.

Mainstay Monday: Managing Type Coercion

If you are new to programming and, especially, to a dynamically typed language like Javascript you are likely not familiar with type coercion. The best way to think about type coercion is, when dealing with two values of different types, the two variables will be normalized to a single variable type for the sake of comparison or other common interaction. The important thing to understand with type coercion is the language interpreter or just in time compiler (JIT) will guess what the type is that you meant to work with and do the “right thing” with it.

Let’s take a look at what type coercion looks like in Javascript.

As you can see, there isn’t a particularly hard and fast rule that one type is always converted to another. More importantly, you can see that the most common cases are strings to and from numbers and vice versa. Numbers coerce to booleans, but strings don’t. For concatenation numbers coerce to strings. For equality it’s unclear which direction the coercion goes and for inequality, strings are coerced to numbers as long as they convert cleanly.

Type coercion is intended to be a convenience feature in Javascript so new programmers don’t need to understand value types deeply enough to perform typecasting. Unfortunately the confusion that comes with type coercion mitigates any benefit even the beginner programmer would gain from it, since it is relatively unpredictable.

Managing Expectations

Since type coercion is unpredictable, we should manage values ourselves and try to be as explicit as possible so we always get results back that we expect. We don’t want addition to concatenate our members if one is accidentally a string. We don’t want to coerce boolean values to numbers or the other way around since the only number that evaluates to false is 0 and there are many times we get values which mean something failed, but the coercion would make them true.

We, basically, don’t want the language to guess what we mean because it is likely to guess wrong. Let’s have a look at some of the things we can do to help improve the reliability of our applications and manage the type coercion that happens with our values throughout our source code.

First, let’s take a look at triple-equals (===). Performing a value conversion at comparison time has two pitfalls. The lesser of the two is, it’s slow. It’s not slow in the way that an O(n^4) algorithm is slow, but it is slower than comparing values directly without conversion. Let’s take a look:

We can see how eliminating coercion from our comparison operations, we get a normalized, type-safe experience while programming. This provides guarantees we otherwise could never get. If the code is changed, potentially in an unstable way, issues will start to emerge that will give us more immediate insight into what is happening.

Let’s have a look at another method for handling type differences: typecasting. Typecasting is something that is very common in strongly typed languages, but is often overlooked in dynamically typed languages like Javascript because it is not immediately obvious why it could be valuable. Let’s compare some of the common ways people manage type differences and how typecasting can help normalize your code and eliminate hacks to get around a common problem.

Typecasting might take a few more keystrokes than one of the hack methods, but it does two things for us that other methods don’t provide. First, typecasting is declarative of intent. By using Boolean or Number, you know precisely what you should be expecting. You will also, get a highly normalized, safe value back. The second thing typecasting offers is a 100% guaranteed type safe expression every time. This means that every comparison, computation, concatenation, etc, will produce a predictable result. Predictability is stability.

Before we finish up, let’s take a look at a couple of other built-in functions that are useful for handling common conversion cases. These functions are specifically for managing number and string outputs. These three functions are parseFloat, parseInt and toString.

ParseFloat takes a single value parameter. ParseInt takes two mandatory values, the value to parse and a radix. A radix is the base the original number is in, which is important for handling things like binary, octal and hexadecimal strings. ToString is a function that exists on the prototype for just about every object in the Javascript ecosystem. Let’s take a look at what

What is happening in Javascript is this, there are language features, i.e. type coercion, that were introduced to make it friendly for people who might not be strong programmers, or may not be programmers at all. Now that Javascript has taken hold as the language of choice for many different applications and we begin solving real problems with focus on real programming, this kind of low-entry-barrier kind of behavior is not preferable.

Like many other high-level, application type programming languages, Javascript has means to handle types with grace and stability. The concept of a type-safe comparison, i.e. triple-equals (===), gives us type guarantees for a variety of conditional cases. Typecasting allows us to explicitly declare the manner in which we intend to use a value, affording us stability when operating with unexpected type variances. Finally, build-in conversion functions and methods allow us to convert a value, store it and use it in a predictable way. This conversion gives us guarantees around the type of a variable as we develop.

The important take-away here is using type coercion is, at best, an unstable way to write programs which could introduce bugs that are difficult to identify and, at worst, a hack that makes code obscure and difficult to maintain. Instead of using type coercion, prefer stable, predictable methods for guaranteeing type and maintain type safety in your programs.

Blog Post Notes

Eliminating Switch Statements with Hashmaps

It has been a really, really long time since I created a switch statement. I’m not saying there is no place for switch statements in programming, I’m just saying, I haven’t had a reason to use one in a long time. Even though I haven’t written a switch in a long time, I have seen them popping up in code examples at work, online and other places a lot lately.

After seeing several different uses, I started asking “what is the programmer really trying to say with these?” Most of the examples I have seen look like the following:

This has a very particular code smell that I haven’t encountered a name for yet. I’m going to call it conditional obsession. In this particular case, the programmer has opted for conditional logic to emulate a well-known and commonly used data structure. Reducing this kind of conditional overhead is akin to using a stack to eliminate recursion.

Switch statements are intended to be a way to simplify multiple conditionals in a more readable way. Since this code is not really, actually handling a set of conditionals, the switch statement has become little more than an extravagant replacement for a hashmap.

For those of you in Javascript land who aren’t familiar with hashmaps, they are a very close relative to the object literal we have all come to know and love. They are so close, in fact, that you can substitute an object literal in for a hashmap at any point in order to maintain an idiomatic look and feel to your code.

Let’s take a look at what a data structure containing our error messages would look like:

Hey, that makes a lot more sense to me. I can look at this and, in a glance I can immediately tell you what our hashmap contains and what the relation means. This, of course, still doesn’t satisfy one thing that a switch statement can do: default behaviors.

Fortunately, we can build a quick, painless mechanism to handle default values and keep all of the readability we have started here.

Now we have reduced our switch statement down to what we really meant to say: find my error message in this set of keys; if a message can’t be found, then provide a default value instead. This leaves us with a single data structure and one conditional that handles the case we were really interested in: when the error code is unknown.

We will need to make one more modification to our original code to really clean it up and give us the clarity we are looking for:

Now sendError doesn’t require every function to perform some preprocessing to capture the error message it needs to send. This reduces the complexity of our code every place an error code switch statement might have existed and allows us to centralize our error messaging and let our core functionality do what it is intended to do.

Here’s our final, refactored code:

Depending on the size and complexity of your code, this refactoring provides the perfect opportunity to abstract all of your error codes out into a centralized configuration file and then provide an error service that will allow you to simply capture an error code and then send it up through the stack and abstract your error messaging away from your core code altogether.

Switch statements, along with other conditional statements, should be used when an action should be taken only when the condition is satisfied. When conditionals are used to replicate core language data structures, it is often preferable to fall back to the core data structure and reduce the complexity of your code. Hashmaps are faster and more intuitive than a switch statement will ever be, so think about your data, refactor your code, then take a couple minutes to marvel at how your code will say what you really meant to say.

Mainstay Monday: Contextual Scope

Last week we kicked off a discussion of scope in source code. We talked about lexical scope and how that impacts the way variables are accessed. There is another element of scoping called contextual binding, which is what gives people the most trouble.

Contextual binding is the scoping of variables based on the execution context of a particular function at the time of execution. This is least visible when dealing with the functional aspects of Javascript and most visible when interacting with objects. Let’s take a look at a little bit of Java to start.

Although there are a few things here and there that might not seem familiar to the average Javascript developer, I’m sure everyone can largely follow along with what is happening here. We’re creating an object that takes a string in its constructor and then prints it to System.out when printVar is called.

Let’s take a look at the equivalent code in Javascript. I’m going to keep this old-school so we can talk about what is happening here without trying to remember all that new-fangled ES6 syntax. (I originally wrote this with a class)

So far, no surprises. Handy thing, that. We did essentially the same thing: we created an object Thingy, instantiated it and then called myInstance.printVar. Everything worked out just as we expected it. Suppose, on the other hand, we were to do something like, hand our function off as a delegate to another function or object. Let’s take a look at what that produces:

I’m sorry, what?

We defined printVar inside myInstance and pointed it at this.someVar. It seems like it shouldn’t return undefined when we call it. This is a product of contextual binding. Although the original context inside our object Thingy provides a value someVar, once the function is passed to another function as a delegate, the context changes. This NEW contextual binding doesn’t provide the same variables as the original, so this.someVar doesn’t mean what it once did.

This behavior is really difficult for people who are new to Javascript. They expect, much like Java, that the original object context is bound up with the functions from the same context. What we can’t do with Java, however, is break a function from its object context and produce a delegate like we are doing here.

Fortunately, Javascript has a way to provide some guarantees! Don’t fret, young padawan, we have the bind function. Bind is a function that is defined on Function.prototype, and allows us to guarantee that a function will execute within a specific context.

Here’s what using bind does for us:

Hooray!

With simple examples like this it’s easy to think that all contextual binding is obvious and simple. I wish it were true. Contextual binding, however, can get a little tricky as functions start getting passed around and you start editing not only your own code, but others’ code too. The important thing to see is that contextual binding is a good place to look when you start coming up against disappearing variables and suddenly undefined values.

By combining lexical scoping and contextual binding, you can get your variable management under control and start writing safe, stable, internally consistent code. You’ll impress your coworkers, be better at sports, your teeth will be whiter and your car will get an extra 5 miles to the gallon. Well, you code will be more stable, so there is that. Watch your scope and context and your code will thank you.

Blog Post Notes

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:

Comments Off on What Makes a Program Stand Up