The Dopefly Tech Blog

Join Nathan Strutz as he shoots the breeze on techie geeky web dev stuff.

I wrote my own: ORM

posted under category: General on October 16, 2021 at 11:53 am by Nathan
A blog series in which I confess to accidentally having written my own poor version of a solved problem

I joined a new project at work. OK, joined is a polite word. A product was thrust into my lap. It has great documentation and lots of clean code written --maybe generated? Nevertheless the generator was missing and so were all the previous developers. One thing it had in spades was a strong MVC N-Tier Architecture. This made it really easy to find things, change things, and understand how the system worked.

By the way - if you do this for your application, you’re doing this for the next dev that maintains your application - and we thank you!

As I maintained this application for a while, I began to notice similarities in parts of the application that really were redundant. Specifically the data access layer. It was split between data access objects (DAOs) and data gateways (DGs). While the DGs had a lot of odds and ends that would return various recordsets, the DAOs had the same system over and over. CRUD. Load a single record and populate a single object. Read a single record and perform an insert or update. Delete a single record from the database.

The only things different were the names of tables and the names of the columns. There were a couple one-off tables without a single PKID column, but those weren’t the meat of the system.

I began to literally sketch out some potential solutions. The end result looked a little bit like this:

partial orm diagram

I began playing with constructing the SQL statements for each table based on component metadata. Properties in my components would probably need some custom metadata, but that both helps get this job done, and self-document the system a little better. Did I mention I was using ColdFusion for this? It makes things so simple. Watch.

The user class starts off looking like this

component {
  property name="id";
  property name="name";
  property name="role";
}

Thanks to ColdFusion’s custom metadata system, I can throw anything I want on there, then pull it out when I’m building my DAO queries.

component table="user" {
  property name="id" pk="true" required="true" sequence="seq_user_id;
  property name="name" type="string" required="true";
  property name="role" type="string";
  property name="someDynamicProperty" persist="false";
}

So on one end, I used this to build my CRUD queries, then on the other side, I used the metadata to map the recordsets back into the models. It was actually pretty simple, once it all worked.

I tried it out for a few new tables as part of a new feature. That’s how you add your innovations and entertainment, by the way – you make the fun stuff a “critical” part of the less-fun stuff. Once that worked, I spread it across the rest of the system. In one day I reduced the codebase by 3,000 lines!

I took it a little further by auto-generating some basic list functions, like the neat little listByCriteria where you send in an object from the table with the properties you want to find.

var criteria = new User();
criteria.setRole("Admin");
var admins = dgo.listByCriteria(criteria);
What did I learn?

It’s a lot of work up front to generate your own queries, but a lot less work in the long run when you know you’re getting the most optimized experience you can. Sure the ORM here was simplistic, but so were the needs of the application.

When you make something that’s like a framework, but it stays as part of a single system, it tends to integrate tighter than you expect. This ORM became an integral part of the application it grew from. The downsides with that are that it would have been very difficult to replace it with a publicly available ORM, and it became harder and harder to reuse it in another system. In this ORM’s case, it never grew out of this application.

Of course, now that other ORMs exist, I don’t think that I would do this again. However… I have another one coming up that would prove me wrong. Stay tuned.

(discuss!)

I Wrote my own: Hybrid SPA+SSR Framework

posted under category: General on October 14, 2021 at 10:24 pm by Nathan
A blog series in which I confess to accidentally having written my own poor version of a solved problem or popular framework

It was 2009, and I thought to myself “jQuery is just so verbose.” I mean look at this code I have to write in order to download an HTML fragment from the server and inject it into an area on my HTML page.

$("#target-area").load("/api/users/list");

OK, Ok, ok. It’s not that bad. But imagine you did this with Prototype.js, the dominant framework before jQuery existed.

new Ajax.Request("/api/users/list", {
  onSuccess: function(response) {
    $("target-area").update(response.responseXML);
  },
});

Or imagine you started the project without a JavaScript framework

function reqListener () {
  var el = document.getElementById("taget-area");
  el.innerHTML = this.responseText;
}

var oReq = new XMLHttpRequest();
oReq.addEventListener("load", reqListener);
oReq.open("GET", "/api/users/list");
oReq.send();

I was on a project for a short time that had hundreds of screens with code like this – all customized for each and every page, all repeated, with so much boilerplate bloat that I questioned the reason for software altogether. If we add input fields into that code along with form submissions, validation, error messages, and so on, you can imagine how quickly we had JavaScript files that were tens of thousands of lines long. Then came the memory leaks, name conflicts, and maintenance.

Yes we could have done better, but I was just a loan-in, and I wanted to see what kinds of things we were building elsewhere in the company. The point is, this application made me afraid of what we could create if we didn’t start thinking about systems to handle bloat before we had problems with it.

I had an idea. What if we could implicitly load content based on some basic HTML, and use jQuery to sniff out what needs to be loaded. Just follow me down this trail for a minute.

What’s an ideal amount of JavaScript to write? None! Stupid question, I know! I figured that this is the perfect job for a data attribute. I only need to tell the content where to go, like so:

<a href="/api/users/list" data-target="#main">Users</a>

The first version of this HTML-powered, server-side rendered app looked something like this:

$(function(){
  $(document).on("a[data-target]").click(function(e){
    e.preventDefault();
    $($(this).data("target")).load($(this).prop("href"));
  });
});

It ballooned up from there, into a few hundred lines of code that handled global and inline loading spinners, delete confirmations, forms, caching, and errors.

Ahh - but you must be thinking: if the server is generating those HTML fragments, what happens when I open the link in a new tab? Well, jQuery’s AJAX api sends a HTTP header to let us know if we are in an AJAX request. With that header in place, the server sends an HTML fragment. When that header isn’t there, the back-end framework will wrap the fragment into the layout and send a full page.

It’s only a matter of the fragment being rendered with the full layout, or without.

Does that really work? Yes! It turns out it works really well. This web app was 100% functional without JavaScript. Why? Convenience! Also, users found they could open links in new tabs without a problem.

In today’s terminology, I think we would call this a hybrid SPA/SSR. Yes the discount, dollar-store version, but still, it fits the bill. Really, it was a pretty successful project.

What did I learn?

When I attempted to adapt it to another application, I learned that I either needed to cut this ‘framework’ up into smaller, individual parts that could be used independently, or bundle it all together as some kind of super-framework. Just taking parts of it was not a portable solution.

That doesn’t mean it was a waste. Not at all. This framework as its own glue for what it is, is a really cool solution that makes one application pretty easy to read and work on.

(discuss!)

I wrote my own: Fusebox

posted under category: General on October 13, 2021 at 11:27 am by Nathan
A blog series in which I confess to accidentally having written my own poor version of a solved problem or popular framework

It was 1999. I worked at a small agency in Alaska, and I just learned to program in ColdFusion. I drank Mountain Dew and exclusively ate from Taco Bell. A guy at work, probably 15 years my senior and trying to escape code, told me about how to arrange an application, recommending that I make a “fusebox” - a big switch statement that would control what gets called and shown. I started piecing it together.

The project was an online storefront for a local music producer. This was my first real programming project at work, if you don’t count small JavaScript image replacement and form validation scripts, way before CSS and HTML would do these things for you! I frequently forget that I’m old until I say things like this.

So I set up a switch statement with the expression being url.action (the action property in the query string). The switch cases are includes to individual view files, or database calls with a redirect back to another action.

Really this isn’t too different from modern-day frameworks - a router, views, and room for back-end activities.

What did I learn?

It was nice to have a central place to apply security and global request filters. With all the requests coming in through this one file, it was the central hub of the application. That also opened it up to trouble. One coding mistake on the switch meant that the whole application was broken. I made a lot of coding mistakes back then, so things broke frequently.

I used an include for the HTML header and footer, so those just got included right on the switch page. Easy way to make a layout, even if it’s rather lame by today’s standards.

I initially had all the database communication right there in the switch. That really doesn’t scale since that flux capacitor there is now doing literally everything for the whole application. Pretty yucky but I didn’t know better.

Also, this being one of my first professional projects ever, I quickly realized the need for better organization by filename taxonomy.

Fusebox

The first version of Fusebox was merely a word, a convention of organization, which was really not much different than what I had built as a teenager. I’m sure it was at least a little more formal than that, but the internet was young and we didn’t exactly google for information – you had to know someone.

The second version of Fusebox had some official files - some amount of hard matter for the framework. Fusebox 3 actually set you up with structure and files and sub-folders of switches - a real framework finally.

Fuesbox eventually became the gold standard for frameworks in the world of ColdFusion. It was a short-lived title, in those years when XML was cool, before object-oriented features were added.

Have you built your own framework like me?

(discuss!)

Coding on a Chromebook

posted under category: IDEs and tools on February 13, 2021 by Nathan

I mentioned how I’m teaching a high school coding class at our home school co-op. At the beginning of the 2020/2021 school year, I specified that students need a Windows laptop, or a Mac if there was no other option. I don’t like to support Apple devices. I specified that no Chromebooks would be allowed in the classroom. It was the right choice last August, but this next school year, I’m going to let Chromebooks in.

Every week I write up a new presentation in Google Slides, and present it to the class on my Chromebook. Between Google Docs for the slides and GitHub for the files, I have access to everything I need across all of my devices. But what about coding on the Chromebook? Aren’t Chromebooks underpowered laptops with nothing but a browser? How’s the coding experience, you ask? I’m so glad you did!

First, you should know that every Chrome OS device is essentially three things:

  1. A Google Chrome web browser device - the classic foundation and namesake it’s had since 2011
  2. An Android tablet with full access to the Google Play store and most Android apps and games, in fairly performant windowed environment, since 2016
  3. A Linux laptop with a Debian terminal that grants full access to apt-get anything you want, since 2018

There are some really great in-browser IDEs, but I like to keep things local and offline, cutting my choices down significantly. There aren’t any great Android-based IDEs that I’ve seen. But wouldn’t you just want to use everyone’s favorite coding tool? That’s right, I want VSCode on my Chromebook. And guess what? It’s become really easy to do this!

The steps have become essentially the same as they would be on any other operating system. Visit the VSCode website, click the giant download button, then double-click the installer. This was much harder only a few months ago! I was taken back when I had the chance to install it on a new device recently. It’s seamless. I also double-checked that it added VSCode as a known repository for the integrated package manager so that upgrading can be done with sudo apt-get update && sudo apt-get upgrade -y. Or of course you can go download the new version and run the installer again. That’s not quite as seamless as it is on Windows, but it’s not bad at all.

At the start of the 2020 schoolyear, I had an outdated Acer R11 Chromebook with a flimsy Celeron CPU. It performed fine, but the lower resolution 11 inch screen was pretty small for the task at hand, and starting VSCode was a commitment.

This year I invested my incredible teaching profits (that’s a joke!) when I found that Lenovo’s Chromebook line finally includes the incredibly affordable and powerful 10th gen i3 model with 8GB of memory. It’s a steal at $440. I’m not trying to advertise, but I do have an affiliate link to look at it on Amazon because it brings me some happiness and maybe you’d like to check it out. Something amazing about this device is that it launches VSCode in about 1 second - there’s no delay. It’s faster than my i7 work laptop. It has plenty of power for this job!

VSCode in Chrome OS

So my Chromebook has VSCode. What next?

Extensions! They all work. Everything I throw at it works perfectly. I’m not missing anything in this department.

Debugging! Works perfectly. I’ve only tried debugging JavaScript, web pages, and C# code, maybe Python last year, and they are every bit as capable as anywhere else.

Coding! Duh. It definitely works.

Anything wrong?

Only one thing doesn’t work for me. It’s the standard Chromebook keyboard. Not even the physical keys, this Lenovo has good feel for such a quiet sound. My gripes are about the keyboard on Chrome OS devices, namely these complaints -

  • The lack of a 6-key insert-delete, home-end, pageup-pagedown block is annoying enough. I miss that on every notebook keyboard though. The problem is that these keys literally don’t exist. On a Windows laptop, I can at least find these keys. They’re often hidden behind a function control key, but they are there. There’s no chance to find them on Chrome hardware.
  • No delete key. There is a way to delete - alt+backspace will delete in front of the cursor, while the standard backspace key only deletes what is behind the cursor. If you ever want to delete a file, you are forced to make the two-finger-salute.
  • Alt + Click is a right-click in Chrome OS, instead of the standard multi-cursor selection combo in VSCode. I suppose this is configurable so I can change it to the Ctrl key, but it’s very annoying.

Of course all of that can be ignored if you plug in an external keyboard. I’m not carrying a keyboard around in my bag, or over to the couch, so I just have to live with the pain.

Wrap-up

Coding on Chrome OS is great with VSCode, and it’s a very workable solution. Get a powerful processor, no Celerons or Pentium chips, and get plenty of memory. If you’re settling down for a long coding session. bring an external keyboard and mouse just like you would want with any laptop. Now that VSCode works flawlessly, the gates are open wide!

(discuss!)

Programming Life Updates

posted under category: Life Events on February 9, 2021 by Nathan

I have a handful of small things that I don’t want to write up in long-form, so here are a bunch of them.

COVID stay-at-home orders have been fine

Ups and downs, for sure. Work had previously taken a hard stance against working virtually. They did a hard 180° last March, and none of us have visited the office once since then. I hope somebody ate that Cliff Bar on my desk. I would like to bring my chair home, however. I have an AmazonBasics chair at home, which was fine for the amount of time I needed it, up until last March. Now I’m wishing I spent more money on it.

Through the Spring, we scheduled theme nights at home. Hawaiian night. Video game night. Science night. We probably had a dozen of them. All the kids got to pick at least one, and we’d use whatever decorations we had to make it a party. I highly recommend this activity.

South Carolina has actually been pretty chill about it. We’re happy enough to mask up, even if it’s just for show, but if that’s what keeps my favorite restaurants open, then I’ll wear 2 masks if I have to. We’ve had a bunch of friends with COVID, but very few serious cases, and no deaths in our circles of friends. My airplane company is struggling though. We’ve had lots of layoffs - some of it for the better but most of it just for the sadder.

Homeschooling has actually been successful

My oldest child graduated high school, a year early, and even started college with a scholarship! As a homeschooling parent, this is a huge win for us. We decided to homeschool her when she started reading chapter books going into kindergarten. I guess firstborns are always early. We’ve been keeping it up, and now really identify ourselves as a homeschooling family. It’s a weird thing, but honestly it just keeps working out. Especially in light of the trainwreck that was 2020.

Both of my teenagers got jobs where they make pretty good money and are liked by their peers. Again, a homeschooling win. They’re responsible, and they make me proud. That makes a dad’s heart warm!

I love Vue.js

I don’t think I’ve talked about it on here. I fell in love with Vue when I first saw it. Actually I created something a lot like it when I first stumbled over my dislike for React, but before Vue was popular enough for me to hear about it. I always say that you need a framework only when you are on the verge of creating it yourself. That’s where you firmly discover your need. I settled for a bastardization of jQuery and Mustache - that’s how much I disliked React.

I understand React, and really I cut my teeth on it as my first all-encompassing JS framework (“but it’s a library” - not when you use Redux, React Router, and the millions of little packages you need to make a React app work), but I just genuinely hated… well… everything about it. It was partly the naming schemes for events (“componentDidUpdate”, “componentWillReceiveProps” - these are terrible!), it was partly that there was essentially no way to progressively implement it into an existing website, partly because you pretty much can’t use it without Babel and everything that entails, partly because the documentation was barely workable, partly because Facebook, partly because they keep changing major things, partly because Hooks aren’t actually a great software development solution, partly because they add feature that never become official (suspense anyone?), largely because everything in React-land is so verbose and involves a lot of typing, partly because the ecosystem is so fragmented and there are actually too many bad choices you can make with libraries and application design that will create terrible programs, partly because JSX is strange and feels very non-standard, and partly, finally, because I really just have my preferences and React isn’t what I prefer. I dislike it. To be a little more fair, the docs have improved, the lifecycle events have evolved a bit, and the code required to make it go has been getting better thanks to functions over classes and the Redux Toolkit over plain Redux.

I really do “get” React - function call in, HTML out. It’s just that Vue is better, faster, more efficient, more obvious and predictable, easier to work with, the tooling is better, the first-party libraries are better, and the happy-path to success is very easy to find. If you’ve ever worked with React and wondered if there’s anything better, there is.

So Vue is my preferred front-end. I like it in the browser as an included script like jQuery. I like it in a manual Webpack that does just enough. I like it wrapped up and intertwined with my back-end. I like it in a full standalone CLI. I love that it grows with whatever project I have for it. Vue is really great.

My preferred back-end

Years ago I swore by ColdFusion. I mean, it was the best thing going in 1998. Way better than… what did we even have back then? ASP. PHP. JSP. Nah bro. Allaire Macromedia Adobe ColdFusion was definitely the easy path. I mentioned a while ago how my lil’ company has been moving us off of that - and for good reason. We can get the same job done in other platforms. They’re different. There’s something about googleable stackoverflow questions that make a lot of platforms work for you. I set out to find out what was up with .NET, and found my way into .NET Core. I’ve always been a fan, as C# was a pet language to me.

A couple years ago, a couple of us met with Damian and some of the .NET team as representatives of the hundreds of ColdFusion programmers at my company. They were really nice, listened to our feedback, showed us some interesting things coming up, and gave us help getting started on converting a 100 year old company to Microsoft’s software stack. It was nice. So I’ve officially jumped ship and have been coding up all of my APIs in .NET Core running on our private cloud over the past few years. It’s been very successful.

Something I didn’t expect though, that I should have seen coming, is that the .NET Core stack has really just become a thin middle layer between a database and a complex UI. Sure every app is different, but we’ve moved a lot of complexity into JavaScript.

I have a little advice for ColdFusion coders. Immerse yourselves in OOP and FP - there are reasons programmers talk about this all the time. In the CF world, you can get away with doing pretty much anything, but in C# your hands are bound - in a good way, but a challenging way. Learning object-oriented programming and functional programming today will pay off both today and tomorrow. Your CFML will be better, and your non-CFML will be better and you’ll be able to switch more easily.

(discuss!)

Scavenger Stroll - My Kids' FLL project to encourage exercise & activity

posted under category: General on November 24, 2020 by Nathan

Every year, thousands of FIRST Lego League (FLL) teams work on an innovation project of some type. This is in addition to the actual Lego-based robotics competition where they solve a number of robotics-based challenges. The competitions can be a lot of fun, definitely full of energy! The annual challenge (not the robot part) is always something new. This year it was creating a solution to make people more active.

This year, my two younger kids’ FIRST Lego League team had an idea about building a scavenger hunt in a nearby park. They came to me with the idea to build a mobile app, and talked about all these bells and whistles. Like any good engineer, I talked them down to something more realistic and achievable. Plus something that’s in my wheelhouse.

Our joint solution was to build a mobile-friendly web site. This gets away from publishing to multiple app stores, paying a developer fee on one of them in particular, and working around bugs from multiple codebases across the different platforms. Of course now that the web app is built, it would be possible to port it through something like Phonegap or NativeScript, but I think the web app will be just fine.

So let’s talk about the scavenger hunt! This team created a list of things to find along the walking paths, took photos of them, and came up with the application’s rules:

  • There are 2 different scavenger hunts
  • Show as many as 10 items at a time
  • Each item has a photo that can zoom in
  • Each item has a checkbox
  • Once they’re all checked, you win - celebrate with fireworks

Items to find are things like certain kinds of trees, categories of animals (reptile, bird), or park locations like the gazebo or the lake. The team also wanted to make sure we had links to find more wildlife info.

After the app is published somewhere, we will put a sign up with a QR code that will link directly to the web app.

Work begins

On our first work night, we set up VSCode LiveShare so that we could all work on the code together at the same time. This was a huge pain to set up, but was an incredible collaborative tool once it was all working.

I showed the kids HTML, CSS, and JavaScript and we built the structure and outline of the web site. It’s just three pages, one JavaScript app that we powered with Vue.js, and light CSS styling on top of Bootstrap. Once it was all done, we practiced pulling and pushing the code into GitHub. Mind you these kids are 10-14 years old. It was really awesome to see them understand it conceptually and then take it home and still push a few more changes!

On the last team night before the QR code sign was printed up, I integrated our Git repo with Netlify - we were up and running in our forever-home within two minutes!

Some of this technology really is just getting so much better. From the libraries I easily integrated, to the free hosting, it was a lot of fun to set up. Maybe the best part though was doing a project like this with my own kids. I loved it, and I hope we can do more things like this in the future.

So without further ado, Scavenger Stroll for Wannamaker Park in North Charleston, SC:

https://wannamaker-scavenger-stroll-2020.netlify.app/

I hope you enjoy it, and I hope it inspires you to do something great.

(discuss!)

I teach coding to high school students

posted under category: General on November 23, 2020 by Nathan

Let me start by saying that we home school. And not just this year.

Initially it was out of a desire to keep our first kid ahead of the learning curve. This smart one was reading before kindergarten. Hey it worked - she graduated a year early and is making her way through college.

Something unexpected that came from this screwball 2020 year was the opportunity to teach a class at a home school co-op. This is essentially a one-day-a-week school experience that teaches those subjects that parents don’t want to do at home. We unashamedly use this for English classes, among a few other things. Families can pick up a class here or there, or build their entire curriculum out of it. There’s nothing home schoolers cherish more than the freedom to make educational choices for themselves, so this works for a lot of people.

We noticed that most of the teachers here fall into a couple small categories: parents of the students, and retired teachers. My wife has a particular interest in personal finance, with the real goal of making a generation of young people who understand things like credit scores and compound interest. So with all the qualifications being met, she’s been teaching her favorite things to high school students.

This year I found some spare time somehow (anyone else with me on that?). My wife put the bug in my ear about teaching a coding class. I really wrestled with what that even meant, and what students could benefit from it. When I heard our last CS teacher moved away over the summer, I knew we had a gap - somebody had to teach a computing credit. So with all the qualifications being met… why not me?

Also, more importantly, how?

I want to teach real languages and programming skills. I want to teach students to actually code, to understand what the computer is doing, and to see things from the inside. All of the curriculum I could find for high school seemed to be based on Scratch or Legos. It’s not that there’s anything wrong with that, just that there aren’t a lot of professional jobs for dragging-and-dropping Scratch blocks.

Maybe I’m a rare gem or something, but I started coding web sites in high school, then graduated and started getting paid to do it that same week. We all know the bar is a lot higher now with front end development being nearly impossible to break into without a good mentor and who-knows-how-many years of practice, but I like to think it’s still possible to start a career coding web sites.

What languages does that leave me with? A lot of options, so let’s rule out anything grossly unpopular, anything with static types because type systems are a little tough for noobs (more on that later), and anything I don’t know (and that’s a lot). Then make a strong preference for those languages that work directly with HTML (haha yeah, ok, that’s a list of 1 now). I thought about Python, and maybe I should have thought harder, but I chose JavaScript.

To be fair, I see some of the folly in my ways. There is a challenge with some kids when programming moves from conceptually understanding what to do, to typing the code out on a keyboard. Furthermore, curly braces and parentheses can get messed up in ways you don’t want to see. Maybe Scratch would have been smart. Maybe Python would have been wiser.

Still, I stand by my decision to use a wider-purpose language than Scratch. JavaScript is debatable for a first language, but I have plans to tie it in with the next semester when we code up HTML and CSS. In fact, I’m planning to use the project that these kids finished the 2020 school year with in their 2021 web site that we are building next semester. This is why Python wouldn’t be my primary choice for a student’s programming language – it lacks that one critical integration: the web browser.

Why HTML and CSS? “Aha those aren’t programming languages!” you may say. And you would be right, but this isn’t a programming class, it’s a coding class. You don’t program HTML, but you do code it! I want these students to be well-rounded in what is debatably the most important software skillset in the history of the world - HTML, CSS, and JavaScript, the fundamental building blocks of the web.

Class started in the fall. 17 students showed up! This is my first class ever, I’m pretty excited! Also nervous. Stomach ache nervous. Stomach aches aren’t a sign of COVID however so forget that! This is just like a conference talk or anything I’ve done before, I’m going to knock it out of the park just based on my vague charm and the meme humor in my slideshow.

Yes, there’s a slideshow! It’s a Google Sheets slide deck. I picked one bold presentation theme for the year and have stuck to it. We’re actually fully on the Google stack of education. I have a Gmail account through the school, a shared Drive, and we are suffering through the underdeveloped early years of Google Classroom, which is still better than most of the alternatives.

One of my students was staying home, hoping to skip past a possible first-wave of COVID-19 as soon as school started, so unless I want to video record the whole thing and post it for the class (hint: I don’t), I’ll need to have some way to transfer the knowledge across the internet so when he finally attends physically, he won’t need to catch up. Every week I post my presentation in Classroom. At first just for him, but then I realized that it’s a great tool for the students to review our lesson, check on what the homework was, and read my possibly embarrassing speaker notes. I love transparency when it comes to learning.

I told the kids that everything that happens inside a computer is knowable - something you can learn. It seems like it’s a sealed black box, but that’s only because you don’t know how to open it yet.

The lessons this semester have been loosely adapted from Eloquent JavaScript. I went through a lot of JavaScript books and curriculum and I decided on this one for a number of reasons. One of which is because the book is completely free, even though I bought a paperback copy to study. The other reason is because I liked the order of the approach - variables, data types, operators, flow control, functions, then objects and arrays. Furthermore, Eloquent JavaScript is modern enough to not recommend you do it all in a browser by including a script tag, which is something common I see as a side effect when teaching a 25 year old language.

So we kicked it off. Leson 1, install VSCode and Node so you can run .js files. Lesson 2, hello world! Then onward and upward from there. We’re only 13 weeks in and that’s the end of the first semester. That’s right, I’m writing this in retrospect of my first half-year! How did it go?

Lessons learned

There can be a mental hang-up when first trying to put code into text, as I said earlier. For some of the students, this was, and still is, a big mental block.

The different braces and brackets are confusing. Why do we use curly braces on if statements and on loops and on functions and on objects too? This is where I began doubting JS and reconsidering Python for next year. At least square brackets usually means we are talking about arrays, and parentheses usually means it has to do with functions.

A student dropped out! He was probably the youngest one in the class, 14. I don’t know if it’s a brain maturity thing that grants the ability to write software, but I think that could contribute to it. Honestly, with my ~3 week introduction, he could probably pick it up and ace it in 2 years. After that, I started pre-presenting the presentations to Elly, my 11 year old. She seemed to get it and helped me smooth over the rougher stuff for the next few weeks. She also wasn’t great at the technical parts of coding, but she understood the concepts. Elly is smart!

Typing speed Something that popped up right away was the fact that most of the class typed under 30 WPM, and we had a few hunt-n-peck typists. I started assigning an amount of typing every week, with the goal of getting at least 60 WPM with proper touch-typing form.

Editing text is a skill that nobody knows without being told. This is one that I remember learning initially, and I still learn new tricks pretty frequently. We had to talk about text navigation, shortcut keys, saving often, and I even had everyone install Prettier to clean up what they’ve written.

Creating files was an actual challenge. There are precisely 44 ways to do it with VSCode (I didn’t count, I’m sure it’s over 6), and I don’t like to force people to do it “my way.” Honestly i don’t even prefer a specific way myself.

The JS Debugger isn’t good enough. There are errors that don’t get shown correctly, and some random outputs that are unexpected, like “Undefined” output randomly and rendering of empty blobs when using console.table. Students are easily confused about that. Then they as me, and I’m easily confused about it.

I assigned FizzBuzz, which is maybe a little sadistic after just a few weeks of classes.

One student nearly finished FizzBuzz before class ended. Everybody else took all week. A couple of them never even turned it in.

We made rock, paper, scissors to practice our skills. That was pretty fun.

Our big project was a card game. Make a card, make a deck, deal a hand to at least 2 players, then declare a winner using whatever rules you want. I recommended high-card, then add poker rules for bonus points. My star student did the easy stuff, then built a blackjack game. Everybody got a passing grade, at least.

I explained functions twice. Maybe three times by the end. It’s a complex solution to a complex problem.

My son wants static typing! He asked me about dealing a hand of cards, and how function parameters work. He noticed it was difficult to tell what the argument in the function was supposed to be. I’m pretty proud of him. Without knowing it, he was asking for a stronger type system.

Throwing errors. The class thought the verbiage was funny. Throwing and catching. We didn’t go over it except in passing, but the terminology is somewhat memorable.

That’s it for now. I have a lot more but can’t think of anything right now. Feel free to ask questions!

(discuss!)

Programming is Hard!

posted under category: Software Quality on February 13, 2020 by Nathan

Maybe you don’t remember, so let me remind us all how hard programming is.

I have four children. Believe me when I say that I have been trying to get them to program from a very young age, and so far it’s not all roses and candy treats. Usually there is an amount of familiarization that a flourishing person needs to have with a subject in order to comprehend it fully. Learning how to read, for example, takes sounding out letters, followed by dick-and-jane books, followed by frustration, some time off (usually months), and then retrying, usually with a higher amount of success. Learning to read is a long process and doing it well involves creating many new brain pathways.

Imagine trying to teach your parents to program. With only a few exceptions, there’s a very high chance they simply won’t be able to get it.

This is something I wrestle with, and recently I’ve come to the conclusion that the standard human brain can’t easily grasp the concept of templating. Instead of building something, we programmers are building something for someone else to build something. The more meta up that chain our brains can go, the better a programmer we tend to be. Problems are always solved on a higher level than they were created.

Let’s say that we learned programming, we make our first application, we send it out for our users to try it, and what happens? It doesn’t work! We thought of every conceivable possibility. The problem was that we didn’t conceive of enough possibilities.

“Software is not governed by Moore’s Law; more like Murphy’s Law”
– Douglas Crockford

Even when we find a good solution, that doesn’t mean we’ve reached programming bliss.

“Some people, when confronted with a problem, think “I know, I’ll use regular expressions.” Now they have two problems.”
– Jamie Zawinski

Sometimes progress is very hard and it can literally take years to get past our hurdles. My friend Ben wrote this a number of years ago:

“Every time I think I am making progress, I come to realize that I only have more confusion over the ‘right’ way to implement something”
– Ben Nadel

But don’t forget, programming is very difficult. It can be near-infinitely complex. Think about this for a couple minutes:

“Computer programs are the most complex things that humans make. Programs are made up of a huge number of parts, expressed as functions, statements, and expressions that are arranged in sequences that must be virtually free of error. The runtime behavior has little resemblance to the program that implements it. Software is usually expected to be modified over the course of its productive life. The process of converting one correct program into a different correct program is extremely challenging.”
– Douglas Crockford

If you’re programming, you are doing something extremely intricate. You are valuable because most people cannot do what you are doing. But wait! Your value isn’t only in programming, you are especially valuable because of your ability to put business processes to computers, and to explain these computer systems back to the business.

(discuss!)

Lines of Code

posted under category: Software Quality on February 7, 2020 by Nathan

One of the oldest and rawest forms of software measurement is the inimitable count of the number of lines of code. Let’s talk about that.

“Measuring programming progress by lines of code is like measuring aircraft building progress by weight.”
-Bill Gates

I work at an airplane manufacturer. We actually know the final delivery weight of an airplane, even adjusted for paint and seating arrangements, and in airplane manufacturing, knowing the current and final weight could help. On the other hand, a work of software is done when all the features are complete and the bugs are worked out, or better yet, when we know it will make or save enough money to start selling or using.

Lines of code differ drastically between systems. Choice of programming language is one of the primary reasons for a drastic change in the lines of code. One lower level language may allow us to implement a solution in 100 lines of code, while a higher level one has it as a built-in-function - one line. That doesn’t mean either language is worse, just different. Typically we see higher level languages develop applications much faster and debug easier thanks to the smaller codebases, but there is a tradeoff in performance and resource usage.

Another distinguishing factor is what function the application is expected to perform. It’s hard to compare a shopping cart system to a manufacturing system, they have completely different uses and thus a line count to compare them does essentially nothing. Perhaps one application is more straightforward and requires less code, even if it produces more in some kind of measurable output.

Then there’s the people problem. A developer on one system may have clever tricks that reduce the line count. This could make the codebase equally better or worse, generally depending on the cleverness of the solution, and thus the cleverness of the programmer. We often think we are smart. 90% of programmers believe they are above average, thanks to the cognitive bias called illusory superiority.

This then leads us to the yin-yang problem. More features need more lines of code, however there is a tax because more lines of code become harder for the software writer to comprehend and modify successfully. This is the exact nature of software complexity, and leads to the introduction of bugs, the creation of testing frameworks, the discussion of software quality, and the entire software industry. Remember that no lines of code means no bugs, no rework, no expensive developers, and no security hacks.

Next, we have to consider how the number of lines are calculated. Does that count include 3rd party libraries? Does it include blank lines and whitespace? Does it include comments? We can make a strong case both that all of these should or should not be included.

Lines of code does tell one one important thing however. It tells us how many lines of code are in the application’s codebase. It can give us a general order of magnitude for what we will find. It can give us the feeling of largeness, especially when we compare file-by-file (though typically a byte count would suffice). That’s it. Number of lines of code can tell us how many lines of code there are. That is all.

(discuss!)

Measuring Software

posted under category: Software Quality on February 1, 2020 by Nathan

Why do we want to measure software?

Software measurement is what we software developers do instinctively when we start a new job, join a new project, or enter a new team. It’s critical for us to understand the scope of a product so that we can learn our boundaries and understand our place. Understanding software is one of our best skills - the others being the ability to explain it, and the ability to write it (okay, there may be more to it). Our fight against the chaos of the unknown requires that we split up what we can observe into categories that we can understand.

Many times I’ve been give a legacy codebase without a proper introduction. That’s the worst feeling, and was my motivation for writing a big post on how much documentation you should have. If we could somehow bottle up this knowledge and pass it on to our colleagues, it could be very beneficial to future maintainers, helping to lower the long tail of operational cost on a product, and maybe even stave off the inevitable retirement of an app and the cost of rewriting it for a long time. And that’s our goal - it’s to remove cost, not to add it. It’s to understand the world and to be able to explain it.

Good measurements of software can bring a valuable understanding to us and to the people paying our bills. Is the software tiny and easy? That’s good to know! Is the software humongous and complex? That’s good to know! Is the software terrible and in dire need of help? That’s good to know!

How do we measure software?

Answer that and you’re likely to get a grant. The truth is, software isn’t specifically measurable, for the same way we can’t make software perfect. Sure, at a certain small size we can verify that it works as expected, but, you know, can it read mail yet?

Every program attempts to expand until it can read mail. Those programs which cannot so expand are replaced by ones which can.
Zawinski’s Law

That’s tongue in cheek. These days we could change Zawinski’s Law to interacting with social media or running as a native mobile app.

Our trouble with measuring software is that measuring by any single logical metric is a sure way to miss the mark altogether. Software measurement has to be on a different level, in fact, many different levels. Measuring software can only be done when we take in a system holistically. That means understanding it on a much broader level.

As soon as we measure the size on disk, somebody’s in there changing things. As soon as we measure the memory footprint, someone logs in, adding data. As soon as we measure the performance, another proces ties up the CPU and throws off our measurements. Software is soft, and changes too frequently to make accurate measurements that matter. Software is fluid, moving from disk to RAM, and transmitting across networks. It doesn’t take much of a program to utilize all of the hardware given it. It seems that simple metrics just won’t be enough to measure software. Measuring software by its metrics can give a picture of the whole, though, and there’s value in that.

When thinking holistically, one of the aspects that would need to be measured is the quality of a work. We need to measure the quality to complete this picture.

How can we measure software quality?

There are more intangible ways of measuring software, such as number of customer requirements, size or activity of the product’s backlog, and number of users. In particular, we can concentrate on the number of logged defects, if they have been logged at all. None of these are a holistic measurement of the quality of a piece of software, but they do help to paint the broad picture.

I believe that quality is a collection of mostly-intangible aspects. This means quality cannot be measured with a number or a picture. I think maybe a dozen pictures and user interviews and developer deep dives could help complete a mental model of the quality of an application.

There are quality metrics, such as the amount of code coverage (amount of code that is covered in unt tests). That’s a potential measurement of quality, but it could still be a terribly built app with great unit tests. Cyclomatic complexity is one of my favorites, having built a McCabe Indexing tool of my own a few years back. It tells you how complex your CFML files and functions are, and can show line-by-line where your most complex areas are. Another one I’ve looked at is function point analysis, which can map the central parts of an application by usage.

Once a software analyst understands the system holistically, they should be able to express that holistic idea to others. Of course this is a breakdown of its own type, and relies on the communication skills of the analyst.

What are the aspects of software quality?

I’ve compiled this list that I’ll go over at a later date, but feel free to suggest more. Quality is:

  • Completeness
  • Conciseness
  • Consistency
  • Debugability
  • Efficiency
  • Extensibility
  • Maintainability
  • Client Portability
  • Server Portability
  • Reliability
  • Security
  • Structuredness
  • Testability
  • Understandability
  • Usability
(discuss!)
Nathan is a software developer at The Boeing Company in Charleston, SC. He is essentially a big programming nerd. Really, you could say that makes him a nerd among nerds. Aside from making software for the web, he plays with tech toys and likes to think about programming's big picture while speaking at conferences and generally impressing people with massive nerdiness and straight-faced sarcastic humor. Nathan got his programming start writing batch files in DOS. It should go without saying, but these thought and opinions have nothing to do with Boeing in any way.
This blog is also available as an RSS 2.0 feed. Click your heels together and click here to contact Nathan.