Code of the Week - April 5, 2016

Found in a legacy project, this line of PHP was intended to mirror DOM indentation in a Drupal theme function. I appreciate that the developer (who, I'm not picking on. I've certainly done worse) was trying to maintain a sense of layout, however, there's roughly a hundred lines of code above this mixing tons of other business logic, meta data aggregation, database queries, and so on. 

Therefore, you're not going to get any sense of the DOM from looking at this function. Instead, you'll get a really funky looking append in the midst of all this chaos. 

A function with these attritubes and a line like this just screams separation of concerns. Needless to say, it was quickly refactored so I could just read the thing. 

You Must Beware of Shadows

The Eighth Commandment of The Little Schemer - use help functions to abstract from representations - is as obvious as most of the Ten Commandments. Of course you would use other functions to support or create abstraction.

To make the case more clearly, the authors attempt to represent primitive numbers with collections of empty lists ( e.g. (()) for one, (()()) for two). This is a new level of parenthetical obnoxiousness, and for a while, the reader may think - “Are they going to do this for the rest of the book?” - because the authors then go on to demonstrate that a lot of the API used thus far in the book, works for this type of representation. But, then there’s lat?

Testing reveals that lat? doesn’t work as expected with such an abstraction. The chapter concludes with the two speakers exchanging:

Is that bad?
You must beware of shadows

This isn’t a very common thing to read in an instructional programming book, hell, you’d be blown away to see this in a cookbook. 

Searching around online, I couldn’t find too many people fleshing out a very thorough explanation other than a couple chat groups and most users said “I guess they mean...but who cares?” or instead just complained about the book’s overall format. I know how I feel.

The phrase is out of place even in The Little Schemer, considering most chapters end with a recommendation to eat sweets. Nonetheless, it is a perfect for what the authors want the reader to consider.

Going back to the Eighth Commandment above, it’s a considerable summation of coding cleaning activities programmers can read up on in books such as Code Complete and Refactoring.

But why end the chapter like this and call the chapter "Shadows"?

It’s obviously a parental-level warning in the family of “Keep your head up.” While a programmer can abstract a lot, the taller an abstraction is built, the greater shadow it may be casting over operations that are still necessary or rarely necessary, which could even be more painful (read the first chapter of Release It!). The shadows cast by the edifice of your abstraction leads ultimately to bugs or worse a crack in the abstraction that can’t be patched.

It’s more delicate and literary warning than was given by Joel Spolsky about frameworks. Spolsky, as usual, is more confrontational, and aside from the possibility of him yelling at me about this topics, Schemers’ warning sticks better. It’s like a cautioning given by an old woman near a dark wood.

However, these shadows are not cast by some creepy tree, but by our own code. It’s ultimately an admonishment to test, check your abstractions in places you wouldn’t necessarily use them and be just as thorough as the creators of the primary methods of your language. And, of course, be afraid.

Brilliance and Thoroughness

I've made a lot of mistakes programming. Naturally, this can start to give you the sense that you may not be as sharp as you had hoped. Typically, I've brushed it off and told myself something about my hard work or persistence. Maybe to spare my ego or to at least give myself a feeling that I had value in the job market place. Regardless, they ultimately didn't make me feel more confident. It's because almost all of my mistakes had nothing to do with being sharp, insightful or clever. 

The classics of programming as a craft - The Pragmatic Programmer, Clean Code, Code Complete - generally boil down to one statement “don’t be lazy.” When I read this statement and all the many ways each author repeats it, and then compare it to my track record, I really fall short of the mark. Not because I am comparing myself to some excellent and well-known professionals; it’s because I trail in one defining quality of professional work -  thoroughness.

To give a simple example of thoroughness - are you the sort of person who moves their furniture when vacuuming or sweeping? Did you wipe down the counter after cooking? Feel your plates after hand washing to make sure they’re not still greasy?

Now, I wouldn’t call not doing these things “lazy,” but thoroughness is requisite skill to not be considered so.

For a long time, both in my kitchen and in code, I believed I could skirt by on tiny details. No need to to check that site in IE, I assume it’s fine. Don’t worry about thinking up a few more test cases, most people will follow the same usage pattern. No one really reads commit messages, so no need to reread them just to be sure they’re clear. I'll rename that variable later. 

None of these are errors or sins, but they are much like a kitchen counter that's never properly wiped down - crumbs congregate under the toaster, there's always a little moisture around the edge of the sink, and when you turn on a stove burner, the room starts to smell like burning carbon. 

It’s not lazy, it’s presumptive hope that everything will work out so you can save a few minutes. Unfortunately, it’s exactly what John Wooden meant when he said - If you don’t have time to do it right, when will you have time to do it again?

The sad thing is, I always assumed that brilliant programmers could just write stuff once and it would be exceptional and work every time. Like the story of Da Vinci drawing a perfect circle to demonstrate his capabilities. Had he erased a couple points and said, “Hold on,” we probably wouldn’t be retelling a most likely made up story. I believed, subconsciously, I needed some time to pass before I would get to that point.

I’m reminded a cookbook by famous molecular gastronomy chef Ferran Adria on his restaurant called El Bulli. In this expensive cinder block of a book, somewhere in the middle, is a series of photos of the staff at El Bulli, cleaning the kitchen, Adria included. The people are wiping down every surface in that kitchen, including the legs of tables, and staring with the intensity that they would their dishes as they plate.

These chefs are brilliant, but to be so, they also have to be thorough about even mundane tasks. Cleaning isn’t beneath them, it’s an essential element to being some of the best cooks in the world. Furthermore, the reason they are at the level, most likely derives from this basic attention to detail, something the customers will never see. Adria's inclusion in these photos demonstrates that this process never goes away. Regardless of how well you cook, how inspired or efficient you are, the counter will still need to be wiped down. 

Back in code, I no longer hope to be the super hacker, smarmy, always-gets-it-right-the-first-time programmer. Instead, I hope to start by cleaning well and see where that takes me.


The Little Schemer

Thanks to Cool Pacific

The Little Schemer spells out in its introduction that the book is about recursion. Generally in programming circles, Schemer is known as a great book for learning about Scheme/Lisp (see Paul Graham for all the praise of Lisp you’ll need) or functional programming. While true, in my recent reading of the book about 20 years after its first edition, the popularity of Schemer is more important in how it presents these ideas then their practicality in code.

Topical Focus

I’ve said before that there needs to be more topically focused short consumable books for programmers, in contrast to giant tomes. It’s rarely that developers need an immense index of a language’s every aspect or need to know every algorithm, but instead they need specific cross-language experiences - algorithmic groups, object-oriented programming, and, as with Schemer, recursion, clocking in at under 190 pages.

The early Lisp families with their annoying parentheses can quickly cause someone new to the language to either give up or invent Haskell. But as this book proves, Scheme’s syntax isn’t the point. The topic is recursion and that’s it. Use a good IDE to help with your parentheses and move on and be done quickly.


Really, Schemer is a Socratic discourse between a very sharp neophyte and his guide. A very short question and answer format is maintained throughout, except for the sprinkling of recursive commandants and a handful of asides.

The format is a breather from syntactically dense books (here’s how you make variables, here’s you make arrays, classes, functions...250 pages later: You know X new JS framework), academically dense books and the “Let’s program to the Extreme with bad jokes” books.

Using this format, Schemer is as nuanced as it comes, often annoyingly so, as the authors walk through recursive functions a logic decision at a time. However, as laborious as this may be, it’s best to listen to the author’s recommendation to not rush your reading no more than you would a good conversation to experience this unique approach to programming pedagogy.

The Why of the How

A large intent of this Socratic method is to really get down to why a person makes the choices they do, which is a lot more interesting and demonstrates expertise. Take an example of asking an interviewee programmer to write out the Shell Sort on a whiteboard versus to have that same person walk you through a short array verbally using that algorithm, meanwhile explaining why it’s more efficient than insertion sort.

In a time when a common complaint is that the rush of new frameworks and languages is overwhelming and something employers except programmers to keep up with, the main question is how do I write something rather than how did the language arise in the way it did.

For its format and focus, The Little Schemer transcends the modern sense of programming instruction. It won’t be taught in a code bootcamp, because in the Schemer’s universe, coding bootcamps don’t exist because you’re not in a hurry to get a job, because there is no job to be had. Only understanding.


Why I Taught Java

When I taught my first programming class this past year, I decided to teach the class in Java. My co-workers at the time gave me a bit of flack for this. I should be teaching Go or Python or something with a little better reputation.

Java was looked at as the C++ killer as I remember when it first came out. It go overhyped, is the bane of everyone’s desktop with near daily updates it seems, and it isn’t the prettiest language compared to more minimal programming styles.

So why bother teaching it? Particularly if it is semantically dense or harder to read?

Platform Accessibility

Java is free, it’s IDE’s are free, and they supposedly work on all systems. Sure, web programming has this quality too, but Java introduces application style development to students that’s different from the web and emphasizes further the use of object-oriented programming.

Furthermore, it provides an introduction to library packages and it gives students the chance to type something and see something happening that’s not the command line.

Compilation and Typing

These are two concepts that we could say aren’t really that big of deal, but they are conceptually necessary for students to grasp. Programs are typically compiled and by just introducing this requirement you can illuminate the critical concepts of a compiler, build pipelines and the different varieties of code that takes you all the way down to the ones and zeroes.

Likewise, typing, while not a huge issue for non-space critical systems like a laptop, inform students how memory allocation works, why people care, and how programs are designed with memory in mind.

It’s more semantics, but a class is supposed to teach concepts as well as practical programming. Those concepts make the practical lessons more effective.

It’s Hard

I believe there’s a certain level of work that’s necessary for a concept to stick with students. The more details, the more attention is demanded and the really important practices of programming tend to become ingrained in the process of memorizing minor details like the labels for different types.

Think about it - when you’re learning typing you are repeatedly thinking about variables and what they really mean, which then lays the groundwork for more complex data types like arrays and finally designing your own types with classes.

It’s Useful

However, they are ready to look at vendor specific-language like C# with a much greater baseline than previously because of Java. Likewise, other languages like Ruby, JavaScript and even something like Arduino programming are all going to look pretty basic and a relief, picking them up with a lot more speed than having to work the opposite way.

I’m sure this sounds like a dad telling shoveling snow builds character. But I’ll take it - when you need to teach novice students, programming too requires character building.

Intuitive vs Powerful

When I describe a certain piece of software, I'll often add to the end of my description that the tool in question is either intuitive or powerful

Simple comparisons like Photoshop vs Preview, Trello vs Jira, Excel vs Google Spreadsheets are demonstrative of these dual principles. Something that is intuitive is easy to pick up, everything to be used is present on the screen, and does a few things well and quickly. In contrast, something that is powerful, has loads of features, complex and detailed minutiae even to do a simple task like saving, and of course, gives you complete control of whatever your subject is.

Generally speaking, most of us don't buy a $600+ copy of Adobe After Effects (well, you can just use Creative Cloud...) if MovieMaker will suffice. We don't need those extra widgets, we only use it every so often and therefore, why pay that much.

After reading Chase Buckley's "The Future is Near: 13 Design Predictions for 2017", specifically prediction #9: Age-Responsive Design, I'd like to suggest software that exists in a specific user instance that lands on a spectrum between the intuitive and powerful. This is software that evolves its complexity based on your use, skill and demands. 

In this case, your software wouldn't necessary be like ever other user's experience. Take a simple example - if you only need the Sum formula in Excel, perhaps you only have a couple options in that formula. Or maybe your Kanban board in Jira looks and interacts a lot more like Trello, and doesn't need to know business value for task unless necessary. 

Naturally, this would mean that our software would be a lot bigger. However, taking Salesforce for example, already a massive system, it seems possible that a large majority of users would like a single interface that evolves with their business needs but begins much simpler. In fact, we know this is the case because of products like SalesforceIQ CRM. 

Unlike Salesforce's divided software products (at least on the front end), I'd suggest a UI that is singular but varied. 

Take a more basic example - this is a Drupal site, I've done Drupal development for years. I would love it if I could put a Drupal site in at least 3 modes - Tumblr-like, Wordpress-like, and finally full powered Drupal. The majority of your super admins in Drupal are typically looking for a strong product, but mainly use it for blogging. Yeah, I could create user roles and customize the experience - specialized content entry forms, menu navigation, and permissions grokking - but I'd love a switch and for the evolving UI to be a conceptual core to Drupal's interface.

Overall, I see three reasons that would push this concept into a mainstream software platform (most likely SaaS). First, a broad base of user types; second, an existing demand for complexity by a core base; third, strong stratification of user types. All you need from there is just to make the UI that works for your types, in the same way as Buckley describes in his article, we can clearly design for different age groups. 


Rummaging around YouTube the other day, I went and looked back over the Google Zeitgeist videos. 

I easily get swept up in these videos, as they are obviously designed to trigger your emotions from the previous year. However, comparing 2014's video (above) with 2011's - 

 - I'm a little disappointed. In 2010, Google's software is the navigator of the video and the experiences, by 2014, the software takes a back seat to treated images. 

When first seeing the 2010 video, I was personally very motivated to improve my software skills, as it was one of the first demonstrations on how much software could impact your life and more richly experience it. Google (or rather Google's advertising crew) show this experience through its dull interface, which our shared experience of using the software. 

Now, it appears that Google is hitting on those triggers I mentioned above and associating itself with anything that happens, which takes away from the software experience. 

Joel on Software

I was introduced to Joel Spolsky’s writing a few years ago when I was learning how to interview and to run a software team. His most famous article, “The Joel Test: 12 Steps to Better Code” may appear pretty basic now, but all the things Joel was recommending were written in the year 2000 before Agile, Atlassian autobots, Chef / Puppet, Jenkins and Vagrant / Docker were considered essential to even a trivial software project.

I admire that a lot. But I wondered if there was any reason to still read Joel on Software, for the first time since its publication eleven years ago.

As it turns out, absolutely.

Early on “The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!)” was a fortunate starter. While I knew what character sets were and have explained to students how a character eventually gets printed on your screen, when I started reading this article, I also had happened upon an annoying character map bug with my website. The article’s history and breakdown of how indecipherable characters appear in your emails, gave me a lot of background to know what the heck I was actually debugging the site.

“Painless Functional Specs” is an excellent pairing to the hundreds of pages of Agile methodology I have read, and that have become a generalized gospel - have faith in Scrum! I’ve learned that while, you emotionally should be flexible to change, use Kanban, take time to refactor, once projects reach a critical mass, you really do yourself a huge favor to have done a chunk of planning up front. In Joel’s belaboured case, specs are not sacrosanct, just starting points, and are what most folks today would consider paper prototypes. I have not done this for many spec projects, and I have a lot incomplete Github.

Finally, in “Don’t Let Architecture Astronauts Fool You,” Spolsky writes - “Remember that the architecture people are solving problems they think they can solve, not problems that are useful to solve.” In the age of exploding frameworks and write-code-without-coding Shangri-la’s, we are, to some degree, only reinforcing existing structures and problem approaches. Not really creating new solutions. Time savers like Rails, Angular, Unity and such are fantastic and a great entry point for those entering particular programming spaces. But as Joel points out - don’t expect a revolution because we’ve gone up one abstraction layer.

I’d add that, there’s tons of great historical information in the book that could only be written by someone living in those times contemporaneously, especially related to industry developments, old (bad) practices in software companies, and even a couple knocks at Duke Nukem Forever’s release cycle.

Ultimately, Spolsky comes off a big like the software version of Anthony Bourdain. Rough on the edges, highly critical, but overall has the best intentions for creating create software and improving people’s lives with software and work lives developing it.

Getting Started with...Curse

I have had loads of books in my life with the titles all along the lines of “Getting Started with…”. These’ll be the genre of programming instructional books that will educate you in something in 24 hours, the weekend, 21 days and so forth. This is where most beginners in any given language get their start.

They’ll be some variants in there - “Beginning…”, “Head First…” - but they’re all essentially the same thing. Learn programming basics, learn the syntax, and learn a couple patterns.

I owe these books a lot and for the most part, picking up a language after knowing a few others, these can cut to the point pretty quickly if you want to skip over the familiar topics. However, within them lurks a danger.

Programming for the most part is kinda boring and requires a definite commitment that isn’t very glamorous, getting back pain and eye problems for the most part. The lure of these books is that you’ll save a lot of time by using this effective self-teaching book and get right to the good stuff, and theoretically a promotion or something.

However, at some point for beginners programming is just going to be hard. And this is where the problems can begin and my book purchasing in the past exploded.

When programming got hard, it was very easy to look at this book from O’Reilly or Sams and think: “The book’s not right. Or the book’s not right for me. I should get another one instead.”

The issue is that certain concepts, varying from person to person, are tough for people. And these ideas, let’s say classes, are pretty ubiquitous and you just have to grind through them. The book isn’t the problem, the learning is. But combine that “Java is easy guys. Let’s have fun” attitude in most of these accessible books, and you’ll end up feeling like an idiot or frustrated with the book.

Surely there’s some bad instructional books out there, but that is less likely the case unless we’re talking Apress.

So beginners, trust me, at some point just sit down and push through your chapter that’s giving you trouble. You don’t need another book, a simpler book, Code Academy or whatever. You just need to try repeatedly, and save a couple bucks in the process.

Get over frameworks.

Years ago I was looking for an answer to a pretty simple CMS question, I believe on WordPress, and not surprisingly, I found an answer on StackOverflow related to whatever random query question I had.

One of the comments stayed with me. In more or less words the user said - “I agree with this solution. Though I usually write my own CMS from project to project so I don’t have to mess with this stuff.

Aside from the useless vanity that this added to the conversation, I was and remain still pretty shocked at this response. 

Certainly on the surface, it’s a bit of trying to show off, but it unfortunately fails. At the initial time, I thought, in my inexperience, “Wow, I wonder how you would make a system like WordPress from scratch."

Today, I’m reminded of Joel Spolsky’s article - “Things you should never do, part one” - shaming folks who casually and often with pride throw out “old” code as if it had rusted. In the article, Spolsky observes that, yeah, learning someone else’s codebase is harder than birthing your own, but provided codebases, whether from a legacy project or from a package CMS framework, have one advantage - they’ve been tested and have loads of bug resistant lines in them.

While I was willing to admit pretty early on that it was a waste of my time to write link functions or SQL sanitizers, when it came to the front end I was pretty adamant that I was not only an expert, but my code was better than dealing with a front end framework whether in for JS or CSS.

Of course I used jQuery and CMS provided JS libraries, but I scoffed at Angular, Ember, and particularly Bootstrap. After all, I didn’t want a site like everyone else, and my service connections would be simpler if I didn’t have to write them around a controller and factory object.


Now look - I love to learn how things work, to get to how a sorting or searching algorithm works, and just feel like I could maybe build something from scratch. I like to think I could butcher a pig if necessary from my years in the kitchen. 

But if you actually are trying to build something - an application with intent, meaning, and users - then there is absolutely no reason to waste your time writing an email validation function or creating your own binding system. If software is about expression, you aren’t expressing yourself. You’re repeating others.

Is there any shame in an architect using a plumber? Does he or she have to design all the pipes? Sure maybe in some cases - but I seriously doubt any architect is crafting their own nails. 

So using front end frameworks like Angular / Ember and Bootstrap as sounding boards let’s dispel a couple ideas (mainly my own) about using frameworks:

I’m cheating myself and not learning because I’m just putting together someone else’s stuff like Legos.

No. In fact the opposite, you are learning how to tackle the problem that your application theoretically solves. Ideally, this is the hard part and unique problem space that you and NO ONE ELSE has. 

Again, if you want to try and make Pac-Man from scratch to learn how a game engine works, by all means, but when you sit down to make your 8-bit art action clone, which is so unique, the thing that you need to focus on is delivering the product. No one is gonna pat you on the back because you wrote an engine from scratch if no one ever plays the game.

I have to undo a bunch of stuff and the framework just gets in my way.

No, just no. If you so chose to use the ‘btn btn-default’ from Bootstrap to style your <button> then you have about 10 CSS rules to override. Furthermore, nothing in the framework is going out of its way to make all buttons do this style. Even if you get an annoying rule like:

strong { font-weight:normal; }  // THIS IS REAL

Just override this. Likewise, you are welcome to not have the application owned by any controllers if you so chose. Even with a server-side framework, you can always plop users into the folder you need and work around routing if so be it. Wanna Drupal site with a Blog powered by Wordpress, and a help section run by Rails then a custom “About Me” page - you can do this.

Oh geeze, there’s always just another framework I’ll have to learn.

Yeah, no shit. That’s called technological progress. Sooner you get over this, the better. There’s a pile of languages to learn, but understand that most languages / frameworks / build tools and so on are related to others and are usually designed to solve a specific problem. They are a tool.

Maybe employers will plaster that you need to know every JS framework under the pale blue moon, but that’s hiring managers trying to cover their asses. You will use the framework that is most appropriate to your problem space, and knowledge in one will most likely support skill acquisition in another.

For example, I worked with Ember professionally for a little bit and ended up loving it. However, when I approached my next spec project, I chose Angular instead as it better integrated with Rails and had a slightly lighter touch than Ember in my opinion. 

What if I need to customize something?

Knock yourself out! You may need some wild form interaction such that Bootstrap isn’t going to cut it. Cool - just use its grid system. Or dont! Need some JS that doesn’t work well with JS frameworks’ Promise system or data binding? Not sure how that would happen - but yeah, go ahead.

One Small Caveat

With a lot of module development particularly with Drupal front end tools, I have seen a giant mess of code that was nearly impossible to undo to make work for my clients’ needs and I’ve had to do basic stuff like Slideshows consistently.

This mainly happens as a lot of modules are created with the following thought in mind: “Hey, I built this really specific tool for my company. Let me make the colors look like Garland, kill the logo and BOOM! open source.”

Totally fair, but where content entry and front end meet, symbiosis is necessary. Often this is what is missing - the front end is provided and then content entry is jammed into there like adding cocktails to a light salad lunch.


Get over it random guy from StackOverflow years ago - use the tools to save time and customize as you need, focusing on your problem / domain space more than your ability to craft something by hand.

Think about it - a custom car may look cool, but damn, I certainly don’t want to be in an accident in one. Use tested software to make your products survivable in the wild.